[Search][Connectors] Update self-managed instructions, copyedit (elas…

…tic#197199) Addresses elastic/search-team#8471 and elastic/search-team#8498 ## Changes in docker_instructions_step.tsx - Simplified and improved Docker setup instructions - Added automatic config.yml file generation with proper escaping - Removed manual config file download step - Added link to example config in elastic/connectors repo - Improved section headings and instructions clarity - Updated text to be more user-friendly and direct ## Changes in deployment.tsx - Updated configuration step description to emphasize automatic generation - Changed "Configure index and API key" to "Generate index and API key" - Improved wording around configuration automation ## Changes in manual_configuration_flyout.tsx - Renamed "CLI" to "Command-line interface" - Added separate "Connectors CLI" text constant - Improved manual configuration description - Enhanced CLI usage instructions with better config.yml references - Made redirect message more direct and clear ## Changes in start_step.tsx - Changed "Set up" to "Setup" - Updated deployment choice text to be more concise - Changed "Self managed" to "Self-managed" - Improved automatic configuration description - Made manual configuration options clearer ## Changes in constants.ts - Simplified Docker run command - Removed verbose comments from Docker command - Updated path handling to use $HOME consistently - Made Docker volume mounting more straightforward ## Changes in run_from_source_step.tsx * Moved all content into an accordion with clearer heading * Improved source code download instructions and button text * Added link to example config file in repository * Enhanced step-by-step instructions with "First", "Next", "Finally" * Improved text clarity and formatting throughout * Added EuiLink component import for the example file link
kapral18 · Oct 24, 2024 · c0254a8 · c0254a8
1 parent 8de3636
commit c0254a8
Show file tree

Hide file tree

Showing 9 changed files with 235 additions and 137 deletions.
diff --git a/...rprise_search_content/components/connector_detail/components/docker_instructions_step.tsx b/...rprise_search_content/components/connector_detail/components/docker_instructions_step.tsx
@@ -7,7 +7,14 @@
 
 import React, { useEffect } from 'react';
 
-import { EuiAccordion, EuiAccordionProps, EuiCode, EuiSpacer, EuiText } from '@elastic/eui';
+import {
+  EuiAccordion,
+  EuiAccordionProps,
+  EuiSpacer,
+  EuiText,
+  EuiLink,
+  EuiCode,
+} from '@elastic/eui';
 
 import { i18n } from '@kbn/i18n';
 import { FormattedMessage } from '@kbn/i18n-react';
@@ -43,6 +50,16 @@ export const DockerInstructionsStep: React.FC<DockerInstructionsStepProps> = ({
     }
   }, [isWaitingForConnector]);
 
+  const configYamlContent = getConnectorTemplate({
+    apiKeyData,
+    connectorData: { id: connectorId, service_type: serviceType },
+    host: elasticsearchUrl,
+  });
+
+  const escapedConfigYamlContent = configYamlContent.replace(/"/g, '\\"').replace(/\$/g, '\\$');
+
+  const createConfigCommand = `mkdir -p "$HOME/elastic-connectors" && echo "${escapedConfigYamlContent}" > "$HOME/elastic-connectors/config.yml"`;
+
   return (
     <>
       <EuiAccordion
@@ -51,67 +68,92 @@ export const DockerInstructionsStep: React.FC<DockerInstructionsStepProps> = ({
         forceState={isOpen}
         buttonContent={
           <EuiText size="s">
-            <p>
+            <h4>
               {i18n.translate(
-                'xpack.enterpriseSearch.connectorDeployment.p.downloadConfigurationLabel',
+                'xpack.enterpriseSearch.connectorDeployment.dockerInstructionsHeading',
                 {
-                  defaultMessage:
-                    'You can either download the configuration file manually or run the following command',
+                  defaultMessage: 'Docker instructions',
                 }
               )}
-            </p>
+            </h4>
           </EuiText>
         }
       >
         <EuiSpacer />
-        <CodeBox
-          showTopBar={false}
-          languageType="bash"
-          codeSnippet={
-            'curl https://raw.githubusercontent.com/elastic/connectors/main/config.yml.example --output </absolute/path/to>/connectors'
-          }
-        />
+        <EuiText size="s">
+          <p>
+            {i18n.translate('xpack.enterpriseSearch.connectorDeployment.p.dockerInstallationNote', {
+              defaultMessage: 'Make sure you have Docker installed on your machine.',
+            })}
+          </p>
+        </EuiText>
+        <EuiSpacer />
+        <EuiText size="s">
+          <h5>
+            {i18n.translate('xpack.enterpriseSearch.connectorDeployment.p.createConfigFileLabel', {
+              defaultMessage: 'Create configuration file',
+            })}
+          </h5>
+          <p>
+            {i18n.translate(
+              'xpack.enterpriseSearch.connectorDeployment.p.createConfigFileInstructions',
+              {
+                defaultMessage:
+                  'You need a configuration file with your Elasticsearch and connector details. In your terminal, run the following command to create the config.yml file:',
+              }
+            )}
+          </p>
+        </EuiText>
+        <EuiSpacer />
+        <CodeBox showTopBar={false} languageType="bash" codeSnippet={createConfigCommand} />
         <EuiSpacer />
         <EuiText size="s">
           <p>
             <FormattedMessage
-              id="xpack.enterpriseSearch.connectorDeployment.p.changeOutputPathLabel"
-              defaultMessage="Change the {output} argument value to the path where you want to save the configuration file."
+              id="xpack.enterpriseSearch.connectorDeployment.p.configFileExplanation"
+              defaultMessage="This command creates a {configFile} file in the {directory} directory with your specific connector and Elasticsearch details."
+              values={{
+                configFile: <EuiCode>config.yml</EuiCode>,
+                directory: <EuiCode>$HOME/elastic-connectors</EuiCode>,
+              }}
+            />
+          </p>
+          <p>
+            <FormattedMessage
+              id="xpack.enterpriseSearch.connectorDeployment.p.exampleConfigFile"
+              defaultMessage="If you want to customize settings later, refer to this {exampleConfigLink}."
               values={{
-                output: <EuiCode>--output</EuiCode>,
+                exampleConfigLink: (
+                  <EuiLink
+                    data-test-subj="enterpriseSearchDockerInstructionsStepExampleConfigFileLink"
+                    href="https://github.com/elastic/connectors/blob/main/config.yml.example"
+                    target="_blank"
+                    external
+                  >
+                    {i18n.translate(
+                      'xpack.enterpriseSearch.connectorDeployment.exampleConfigLinkText',
+                      {
+                        defaultMessage: 'example config file',
+                      }
+                    )}
+                  </EuiLink>
+                ),
               }}
             />
           </p>
         </EuiText>
         <EuiSpacer />
-        <FormattedMessage
-          id="xpack.enterpriseSearch.connectorDeployment.p.editConfigYamlLabel"
-          defaultMessage="Edit the {configYaml} file and provide the next credentials"
-          values={{
-            configYaml: <EuiCode>config.yml</EuiCode>,
-          }}
-        />
-        <EuiSpacer />
-        <CodeBox
-          showTopBar={false}
-          languageType="yaml"
-          codeSnippet={getConnectorTemplate({
-            apiKeyData,
-            connectorData: {
-              id: connectorId ?? '',
-              service_type: serviceType ?? '',
-            },
-            host: elasticsearchUrl,
-          })}
-        />
-        <EuiSpacer />
-        <EuiText size="m">
+        <EuiText size="s">
+          <h5>
+            {i18n.translate('xpack.enterpriseSearch.connectorDeployment.p.runContainerLabel', {
+              defaultMessage: 'Run container',
+            })}
+          </h5>
           <p>
             {i18n.translate(
               'xpack.enterpriseSearch.connectorDeployment.p.runTheFollowingCommandLabel',
               {
-                defaultMessage:
-                  'Run the following command in your terminal. Make sure you have Docker installed on your machine',
+                defaultMessage: 'Run the following command to start the container:',
               }
             )}
           </p>

diff --git a/...enterprise_search_content/components/connector_detail/components/run_from_source_step.tsx b/...enterprise_search_content/components/connector_detail/components/run_from_source_step.tsx
@@ -19,6 +19,7 @@ import {
   EuiIcon,
   EuiSpacer,
   EuiText,
+  EuiLink,
 } from '@elastic/eui';
 
 import { i18n } from '@kbn/i18n';
@@ -54,65 +55,102 @@ export const RunFromSourceStep: React.FC<RunFromSourceStepProps> = ({
 
   return (
     <>
-      <EuiText size="m">
-        <p>
-          {i18n.translate(
-            'xpack.enterpriseSearch.connectorDeployment.p.addTheFollowingConfigurationLabel',
-            {
-              defaultMessage: 'Clone or download the repo to your local machine',
-            }
-          )}
-        </p>
-      </EuiText>
-      <EuiSpacer size="s" />
-      <EuiCode>git clone https://github.com/elastic/connectors</EuiCode>&nbsp;&nbsp;&nbsp;
-      {i18n.translate('xpack.enterpriseSearch.connectorDeployment.orLabel', {
-        defaultMessage: 'or',
-      })}
-      &nbsp;&nbsp;&nbsp;
-      <EuiButton
-        data-test-subj="enterpriseSearchConnectorDeploymentGoToSourceButton"
-        iconType="logoGithub"
-        href="https://github.com/elastic/connectors"
-        target="_blank"
-      >
-        <EuiFlexGroup responsive={false} gutterSize="xs">
-          <EuiFlexItem>
-            {i18n.translate('xpack.enterpriseSearch.connectorDeployment.goToSourceButtonLabel', {
-              defaultMessage: 'Go to Source',
-            })}
-          </EuiFlexItem>
-          <EuiFlexItem grow={false}>
-            <EuiIcon type="popout" />
-          </EuiFlexItem>
-        </EuiFlexGroup>
-      </EuiButton>
-      <EuiSpacer size="s" />
       <EuiAccordion
-        id="collapsibleAccordion"
+        id="runFromSourceAccordion"
         onToggle={() => setIsOpen(isOpen === 'closed' ? 'open' : 'closed')}
         forceState={isOpen}
         buttonContent={
-          <EuiText size="s">
-            <p>
-              <FormattedMessage
-                id="xpack.enterpriseSearch.connectorDeployment.p.editConfigLabel"
-                defaultMessage="Edit the {configYaml} file and provide the following configuration"
-                values={{
-                  configYaml: (
-                    <EuiCode>
-                      {i18n.translate(
-                        'xpack.enterpriseSearch.connectorDeployment.configYamlCodeBlockLabel',
-                        { defaultMessage: 'config.yml' }
-                      )}
-                    </EuiCode>
-                  ),
-                }}
-              />
-            </p>
+          <EuiText size="m">
+            <h5>
+              {i18n.translate('xpack.enterpriseSearch.connectorDeployment.runFromSourceTitle', {
+                defaultMessage: 'Run connector service from source',
+              })}
+            </h5>
           </EuiText>
         }
       >
+        <EuiSpacer size="s" />
+        <EuiText size="s">
+          <h5>
+            {i18n.translate('xpack.enterpriseSearch.connectorDeployment.p.cloneRepositoryLabel', {
+              defaultMessage: 'Clone the repository',
+            })}
+          </h5>
+          <p>
+            {i18n.translate(
+              'xpack.enterpriseSearch.connectorDeployment.p.addTheFollowingConfigurationLabel',
+              {
+                defaultMessage: 'First, you need to clone or download the repo:',
+              }
+            )}
+          </p>
+        </EuiText>
+        <EuiSpacer size="s" />
+        <EuiCode>git clone https://github.com/elastic/connectors</EuiCode>&nbsp;&nbsp;&nbsp;
+        {i18n.translate('xpack.enterpriseSearch.connectorDeployment.orLabel', {
+          defaultMessage: 'or',
+        })}
+        &nbsp;&nbsp;&nbsp;
+        <EuiButton
+          data-test-subj="enterpriseSearchConnectorDeploymentGoToSourceButton"
+          iconType="logoGithub"
+          href="https://github.com/elastic/connectors"
+          target="_blank"
+        >
+          <EuiFlexGroup responsive={false} gutterSize="xs">
+            <EuiFlexItem>
+              {i18n.translate('xpack.enterpriseSearch.connectorDeployment.goToSourceButtonLabel', {
+                defaultMessage: 'Download source',
+              })}
+            </EuiFlexItem>
+            <EuiFlexItem grow={false}>
+              <EuiIcon type="popout" />
+            </EuiFlexItem>
+          </EuiFlexGroup>
+        </EuiButton>
+        <EuiText size="s">
+          <h5>
+            {i18n.translate('xpack.enterpriseSearch.connectorDeployment.p.createConfigFileLabel', {
+              defaultMessage: 'Create configuration file',
+            })}
+          </h5>
+          <p>
+            {i18n.translate('xpack.enterpriseSearch.connectorDeployment.p.navigateToRootLabel', {
+              defaultMessage:
+                'Navigate to the root of your cloned repository and create a configuration file:',
+            })}
+          </p>
+        </EuiText>
+        <EuiSpacer size="s" />
+        <CodeBox
+          showTopBar={false}
+          languageType="bash"
+          codeSnippet="cd connectors && touch config.yml"
+        />
+        <EuiSpacer size="s" />
+        <EuiText size="s">
+          <h5>
+            {i18n.translate('xpack.enterpriseSearch.connectorDeployment.p.populateConfigLabel', {
+              defaultMessage: 'Populate configuration file',
+            })}
+          </h5>
+          <p>
+            <FormattedMessage
+              id="xpack.enterpriseSearch.connectorDeployment.p.createConfigLabel"
+              defaultMessage="The previous command creates a {configYaml} file. Copy and paste the following configuration into that file:"
+              values={{
+                configYaml: (
+                  <EuiCode>
+                    {i18n.translate(
+                      'xpack.enterpriseSearch.connectorDeployment.configYamlCodeBlockLabel',
+                      { defaultMessage: 'config.yml' }
+                    )}
+                  </EuiCode>
+                ),
+              }}
+            />
+          </p>
+        </EuiText>
         <EuiSpacer size="s" />
         <CodeBox
           showTopBar={false}
@@ -126,15 +164,47 @@ export const RunFromSourceStep: React.FC<RunFromSourceStepProps> = ({
             host: elasticsearchUrl,
           })}
         />
-        <EuiSpacer />
+        <EuiSpacer size="s" />
         <EuiText size="s">
           <p>
-            {i18n.translate('xpack.enterpriseSearch.connectorDeployment.p.compileAndRunLabel', {
-              defaultMessage: 'Compile and run',
+            <FormattedMessage
+              id="xpack.enterpriseSearch.connectorDeployment.customizeSettingsLabel"
+              defaultMessage="If you want to customize settings later, refer to this {exampleFile}."
+              values={{
+                exampleFile: (
+                  <EuiLink
+                    data-test-subj="enterpriseSearchRunFromSourceStepExampleFileLink"
+                    href="https://github.com/elastic/connectors/blob/main/config.yml.example"
+                    target="_blank"
+                    external
+                  >
+                    {i18n.translate(
+                      'xpack.enterpriseSearch.connectorDeployment.exampleConfigFileLinkLabel',
+                      { defaultMessage: 'example file' }
+                    )}
+                  </EuiLink>
+                ),
+              }}
+            />
+          </p>
+        </EuiText>
+        <EuiSpacer size="m" />
+        <EuiText size="s">
+          <h5>
+            {i18n.translate('xpack.enterpriseSearch.connectorDeployment.p.compileAndRunTitle', {
+              defaultMessage: 'Run the connector service',
             })}
+          </h5>
+          <p>
+            {i18n.translate(
+              'xpack.enterpriseSearch.connectorDeployment.p.compileAndRunInstructions',
+              {
+                defaultMessage: 'Finally, compile and run the connector service source code:',
+              }
+            )}
           </p>
         </EuiText>
-        <EuiSpacer />
+        <EuiSpacer size="s" />
         <CodeBox
           showTopBar={false}
           languageType="bash"
@@ -143,6 +213,7 @@ export const RunFromSourceStep: React.FC<RunFromSourceStepProps> = ({
                               make run
                               `}
         />
+        <EuiSpacer size="s" />
       </EuiAccordion>
     </>
   );