[8.x] [Search][Connectors] Update self-managed instructions, copyedit (…

…elastic#197199) (elastic#197577)

# Backport

This will backport the following commits from `main` to `8.x`:
- [[Search][Connectors] Update self-managed instructions, copyedit
(elastic#197199)](elastic#197199)

<!--- Backport version: 9.4.3 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Liam
Thompson","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-10-24T08:29:17Z","message":"[Search][Connectors]
Update self-managed instructions, copyedit (elastic#197199)\n\nAddresses
elastic/search-team#8471
and\r\nhttps://github.com/elastic/search-team/issues/8498\r\n\r\n##
Changes in docker_instructions_step.tsx\r\n- Simplified and improved
Docker setup instructions\r\n- Added automatic config.yml file
generation with proper escaping\r\n- Removed manual config file download
step\r\n- Added link to example config in elastic/connectors repo\r\n-
Improved section headings and instructions clarity\r\n- Updated text to
be more user-friendly and direct\r\n\r\n## Changes in
deployment.tsx\r\n- Updated configuration step description to emphasize
automatic\r\ngeneration\r\n- Changed \"Configure index and API key\" to
\"Generate index and API key\"\r\n- Improved wording around
configuration automation\r\n\r\n## Changes in
manual_configuration_flyout.tsx\r\n- Renamed \"CLI\" to \"Command-line
interface\"\r\n- Added separate \"Connectors CLI\" text constant\r\n-
Improved manual configuration description\r\n- Enhanced CLI usage
instructions with better config.yml references\r\n- Made redirect
message more direct and clear\r\n\r\n## Changes in start_step.tsx\r\n-
Changed \"Set up\" to \"Setup\"\r\n- Updated deployment choice text to
be more concise\r\n- Changed \"Self managed\" to \"Self-managed\"\r\n-
Improved automatic configuration description\r\n- Made manual
configuration options clearer\r\n\r\n## Changes in constants.ts\r\n-
Simplified Docker run command\r\n- Removed verbose comments from Docker
command\r\n- Updated path handling to use $HOME consistently\r\n- Made
Docker volume mounting more straightforward\r\n\r\n## Changes in
run_from_source_step.tsx\r\n* Moved all content into an accordion with
clearer heading\r\n* Improved source code download instructions and
button text\r\n* Added link to example config file in repository\r\n*
Enhanced step-by-step instructions with \"First\", \"Next\",
\"Finally\"\r\n* Improved text clarity and formatting throughout\r\n*
Added EuiLink component import for the example file
link","sha":"c0254a8a554b29e611129d97712327432dc34966","branchLabelMapping":{"^v9.0.0$":"main","^v8.17.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","v9.0.0","Team:Search","v8.16.0","backport:version","v8.17.0"],"title":"[Search][Connectors]
Update self-managed instructions,
copyedit","number":197199,"url":"https://github.com/elastic/kibana/pull/197199","mergeCommit":{"message":"[Search][Connectors]
Update self-managed instructions, copyedit (elastic#197199)\n\nAddresses
elastic/search-team#8471
and\r\nhttps://github.com/elastic/search-team/issues/8498\r\n\r\n##
Changes in docker_instructions_step.tsx\r\n- Simplified and improved
Docker setup instructions\r\n- Added automatic config.yml file
generation with proper escaping\r\n- Removed manual config file download
step\r\n- Added link to example config in elastic/connectors repo\r\n-
Improved section headings and instructions clarity\r\n- Updated text to
be more user-friendly and direct\r\n\r\n## Changes in
deployment.tsx\r\n- Updated configuration step description to emphasize
automatic\r\ngeneration\r\n- Changed \"Configure index and API key\" to
\"Generate index and API key\"\r\n- Improved wording around
configuration automation\r\n\r\n## Changes in
manual_configuration_flyout.tsx\r\n- Renamed \"CLI\" to \"Command-line
interface\"\r\n- Added separate \"Connectors CLI\" text constant\r\n-
Improved manual configuration description\r\n- Enhanced CLI usage
instructions with better config.yml references\r\n- Made redirect
message more direct and clear\r\n\r\n## Changes in start_step.tsx\r\n-
Changed \"Set up\" to \"Setup\"\r\n- Updated deployment choice text to
be more concise\r\n- Changed \"Self managed\" to \"Self-managed\"\r\n-
Improved automatic configuration description\r\n- Made manual
configuration options clearer\r\n\r\n## Changes in constants.ts\r\n-
Simplified Docker run command\r\n- Removed verbose comments from Docker
command\r\n- Updated path handling to use $HOME consistently\r\n- Made
Docker volume mounting more straightforward\r\n\r\n## Changes in
run_from_source_step.tsx\r\n* Moved all content into an accordion with
clearer heading\r\n* Improved source code download instructions and
button text\r\n* Added link to example config file in repository\r\n*
Enhanced step-by-step instructions with \"First\", \"Next\",
\"Finally\"\r\n* Improved text clarity and formatting throughout\r\n*
Added EuiLink component import for the example file
link","sha":"c0254a8a554b29e611129d97712327432dc34966"}},"sourceBranch":"main","suggestedTargetBranches":["8.16","8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/197199","number":197199,"mergeCommit":{"message":"[Search][Connectors]
Update self-managed instructions, copyedit (elastic#197199)\n\nAddresses
elastic/search-team#8471
and\r\nhttps://github.com/elastic/search-team/issues/8498\r\n\r\n##
Changes in docker_instructions_step.tsx\r\n- Simplified and improved
Docker setup instructions\r\n- Added automatic config.yml file
generation with proper escaping\r\n- Removed manual config file download
step\r\n- Added link to example config in elastic/connectors repo\r\n-
Improved section headings and instructions clarity\r\n- Updated text to
be more user-friendly and direct\r\n\r\n## Changes in
deployment.tsx\r\n- Updated configuration step description to emphasize
automatic\r\ngeneration\r\n- Changed \"Configure index and API key\" to
\"Generate index and API key\"\r\n- Improved wording around
configuration automation\r\n\r\n## Changes in
manual_configuration_flyout.tsx\r\n- Renamed \"CLI\" to \"Command-line
interface\"\r\n- Added separate \"Connectors CLI\" text constant\r\n-
Improved manual configuration description\r\n- Enhanced CLI usage
instructions with better config.yml references\r\n- Made redirect
message more direct and clear\r\n\r\n## Changes in start_step.tsx\r\n-
Changed \"Set up\" to \"Setup\"\r\n- Updated deployment choice text to
be more concise\r\n- Changed \"Self managed\" to \"Self-managed\"\r\n-
Improved automatic configuration description\r\n- Made manual
configuration options clearer\r\n\r\n## Changes in constants.ts\r\n-
Simplified Docker run command\r\n- Removed verbose comments from Docker
command\r\n- Updated path handling to use $HOME consistently\r\n- Made
Docker volume mounting more straightforward\r\n\r\n## Changes in
run_from_source_step.tsx\r\n* Moved all content into an accordion with
clearer heading\r\n* Improved source code download instructions and
button text\r\n* Added link to example config file in repository\r\n*
Enhanced step-by-step instructions with \"First\", \"Next\",
\"Finally\"\r\n* Improved text clarity and formatting throughout\r\n*
Added EuiLink component import for the example file
link","sha":"c0254a8a554b29e611129d97712327432dc34966"}},{"branch":"8.16","label":"v8.16.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.x","label":"v8.17.0","branchLabelMappingKey":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

Co-authored-by: Liam Thompson <[email protected]>

x-pack/plugins/enterprise_search/public/applications/enterprise_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>

x-pack/plugins/enterprise_search/public/applications/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>
     </>
   );