Commit cbe1375f authored by Michael Kebe's avatar Michael Kebe
Browse files

Merge branch 'cleanup-readme' into 'main' 

docs: typos, remove port :2375 to avoid confusion with dockerd tcp socket

See merge request to-be-continuous/docker-compose!3
parents 13c68b83 09a5d63b

README.md

+34 −34
Original line number Diff line number Diff line
@@ -19,9 +19,9 @@ include: 
    inputs:

      # ⚠ this is only an example

      base-app-name: wonderapp

      review-docker-host: "ssh://docker@192.168.64.5:2375" # enable review env

      staging-docker-host: "ssh://docker@192.168.64.6:2375" # enable staging env

      prod-docker-host: "ssh://docker@192.168.64.7:2375" # enable production env

      review-docker-host: "ssh://user@192.168.64.5" # enable review env

      staging-docker-host: "ssh://user@192.168.64.6" # enable staging env

      prod-docker-host: "ssh://user@192.168.64.7" # enable production env

```



### Use as a CI/CD template (legacy)
@@ -39,9 +39,9 @@ variables: 
  # 2: set/override template variables

  # ⚠ this is only an example

  DCMP_BASE_APP_NAME: wonderapp

  DCMP_REVIEW_DOCKER_HOST: "ssh://docker@192.168.64.5:2375" # enable review env

  DCMP_STAGING_DOCKER_HOST: "ssh://docker@192.168.64.6:2375" # enable staging env

  DCMP_PROD_DOCKER_HOST: "ssh://docker@192.168.64.7:2375" # enable production env

  DCMP_REVIEW_DOCKER_HOST: "ssh://user@192.168.64.5" # enable review env

  DCMP_STAGING_DOCKER_HOST: "ssh://user@192.168.64.6" # enable staging env

  DCMP_PROD_DOCKER_HOST: "ssh://user@192.168.64.7" # enable production env

```



## Understand
@@ -96,7 +96,7 @@ You're free to enable whichever or both, and you can also choose your deployment 
The Docker Compose template supports [deployment on remote Docker hosts](https://www.docker.com/blog/how-to-deploy-on-remote-docker-hosts-with-docker-compose/), using 

dedicated variables:



* `DCMP_REVIEW_DOCKER_HOST`, `DCMP_INTEG_DOCKER_HOST`, `DCMP_STAGING_DOCKER_HOST` and `DCMP_PROD_DOCKER_HOST` to both enable and configure the target Docker host for each environment (ex: `ssh://docker@192.168.64.5:2375`),

* `DCMP_REVIEW_DOCKER_HOST`, `DCMP_INTEG_DOCKER_HOST`, `DCMP_STAGING_DOCKER_HOST` and `DCMP_PROD_DOCKER_HOST` to both enable and configure the target Docker host for each environment (ex: `ssh://user@192.168.64.5`),

* :lock: `DCMP_SSH_PRIVATE_KEY`, :lock: `DCMP_REVIEW_SSH_PRIVATE_KEY`, :lock: `DCMP_INTEG_SSH_PRIVATE_KEY`, :lock: `DCMP_STAGING_SSH_PRIVATE_KEY` and :lock: `DCMP_PROD_SSH_PRIVATE_KEY` to provide the global or per env SSH private key (in case SSH authentication is required).



### Deployment context variables
@@ -116,13 +116,13 @@ By construction, it is suitable for inclusion in DNS, URLs, Kubernetes labels... 
It is built from:



* the application _base name_ (defaults to `$CI_PROJECT_NAME` but can be overridden globally and/or per deployment environment - _see configuration variables_)

* GitLab predefined `$CI_ENVIRONMENT_SLUG` variable ([sluggified](https://en.wikipedia.org/wiki/Clean_URL#Slug) name, truncated to 24 characters)

* GitLab predefined `$CI_ENVIRONMENT_SLUG` variable ([slugified](https://en.wikipedia.org/wiki/Clean_URL#Slug) name, truncated to 24 characters)



The `${environment_name}` variable is then evaluated as:



* `<app base name>` for the production environment

* `<app base name>-$CI_ENVIRONMENT_SLUG` for all other deployment environments

* :bulb: `${environment_name}` can also be overriden per environment with the appropriate configuration variable

* :bulb: `${environment_name}` can also be overridden per environment with the appropriate configuration variable



Examples (with an application's base name `myapp`):
@@ -176,12 +176,12 @@ Examples with different combinations of files: 
      <td colspan="4" align=center><code>compose.yaml</code></td>

    </tr>

    <tr>

      <td>- <code>compose.yaml</code><br/>- <code>compose-production.yaml<code></td>

      <td>- <code>compose.yaml</code><br/>- <code>compose-production.yaml</code></td>

      <td colspan="3" align=center><code>compose.yaml</code></td>

      <td align=center><code>compose-production.yaml</code></td>

    </tr>

    <tr>

      <td>- <code>docker-compose.yml</code><br/>- <code>docker-compose-production.override.yml<code></td>

      <td>- <code>docker-compose.yml</code><br/>- <code>docker-compose-production.override.yml</code></td>

      <td colspan="3" align=center><code>docker-compose.yml</code></td>

      <td align=center><code>docker-compose.yml</code> + <code>docker-compose-production.override.yml</code> (merged)</td>

    </tr>
@@ -243,7 +243,7 @@ Part of this complexity can be handled by the lookup strategies described above 
3. any [custom variable](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-docker-host)

   (ex: `${SECRET_TOKEN}` that you have set in your project CI/CD variables)



Be aware that environment variables may be freely used and substitued in [dotenv files](https://docs.docker.com/compose/environment-variables/env-file/) 

Be aware that environment variables may be freely used and substituted in [dotenv files](https://docs.docker.com/compose/environment-variables/env-file/) 

using the appropriate [interpolation syntax](https://docs.docker.com/compose/environment-variables/env-file/#interpolation).



### Environments URL management
@@ -332,8 +332,8 @@ They are **disabled by default** and can be enabled by setting the `DCMP_REVIEW_ 
Here are variables supported to configure review environments:



| Input / Variable         | Description                                                                                                       | Default value     |

| ------------------------ | -------------------------------------- | ----------------- |

| `review-docker-host` / `DCMP_REVIEW_DOCKER_HOST`     | Docker Host for `review` env (ex: `ssh://docker@docker-host-for-review:2375`) | _none_ (disabled) |

| ------------------------ |-------------------------------------------------------------------------------------------------------------------| ----------------- |

| `review-docker-host` / `DCMP_REVIEW_DOCKER_HOST`     | Docker Host for `review` env (ex: `ssh://user@docker-host-for-review`)                                            | _none_ (disabled) |

| :lock: `DCMP_REVIEW_SSH_PRIVATE_KEY` | `review` env specific SSH key to use when connecting to Docker Host over SSH                                      | `$DCMP_SSH_PRIVATE_KEY` |

| `review-app-name` / `DCMP_REVIEW_APP_NAME`    | Application name for `review` env                                                                                 | `"${DCMP_BASE_APP_NAME}-${CI_ENVIRONMENT_SLUG}"` (ex: `myproject-review-fix-bug-12`) |

| `review-environment-url` / `DCMP_REVIEW_ENVIRONMENT_URL`| The review environments url _(only define for static environment URLs declaration and if different from default)_ | `$DCMP_ENVIRONMENT_URL` |
@@ -348,8 +348,8 @@ It is **disabled by default** and can be enabled by setting the `DCMP_INTEG_DOCK 
Here are variables supported to configure the integration environment:



| Input / Variable         | Description                                                                                                          | Default value     |

| ------------------------ | -------------------------------------- | ----------------- |

| `integ-docker-host` / `DCMP_INTEG_DOCKER_HOST`      | Docker Host for `integration` env (ex: `ssh://docker@docker-host-for-integ:2375`) | _none_ (disabled) |

| ------------------------ |----------------------------------------------------------------------------------------------------------------------| ----------------- |

| `integ-docker-host` / `DCMP_INTEG_DOCKER_HOST`      | Docker Host for `integration` env (ex: `ssh://user@docker-host-for-integ`)                                       | _none_ (disabled) |

| :lock: `DCMP_INTEG_SSH_PRIVATE_KEY` | `integration` env specific SSH key to use when connecting to Docker Host over SSH                                    | `$DCMP_SSH_PRIVATE_KEY` |

| `integ-app-name` / `DCMP_INTEG_APP_NAME`     | Application name for `integration` env                                                                               | `${DCMP_BASE_APP_NAME}-integration` |

| `integ-environment-url` / `DCMP_INTEG_ENVIRONMENT_URL`| The integration environment url _(only define for static environment URLs declaration and if different from default)_ | `$DCMP_ENVIRONMENT_URL` |
@@ -364,8 +364,8 @@ It is **disabled by default** and can be enabled by setting the `DCMP_STAGING_DO 
Here are variables supported to configure the staging environment:



| Input / Variable         | Description                                                                                                       | Default value     |

| ------------------------ | -------------------------------------- | ----------------- |

| `staging-docker-host` / `DCMP_STAGING_DOCKER_HOST`    | Docker Host for `staging` env (ex: `ssh://docker@docker-host-for-staging:2375`) | _none_ (disabled) |

| ------------------------ |-------------------------------------------------------------------------------------------------------------------| ----------------- |

| `staging-docker-host` / `DCMP_STAGING_DOCKER_HOST`    | Docker Host for `staging` env (ex: `ssh://user@docker-host-for-staging`)                                          | _none_ (disabled) |

| :lock: `DCMP_STAGING_SSH_PRIVATE_KEY` | `staging` env specific SSH key to use when connecting to Docker Host over SSH                                     | `$DCMP_SSH_PRIVATE_KEY` |

| `staging-app-name` / `DCMP_STAGING_APP_NAME`   | Application name for `staging` env                                                                                | `${DCMP_BASE_APP_NAME}-staging` |

| `staging-environment-url` / `DCMP_STAGING_ENVIRONMENT_URL`| The staging environment url _(only define for static environment URLs declaration and if different from default)_ | `$DCMP_ENVIRONMENT_URL` |
@@ -379,8 +379,8 @@ It is **disabled by default** and can be enabled by setting the `DCMP_PROD_DOCKE 
Here are variables supported to configure the production environment:



| Input / Variable          | Description                                                                                                         | Default value     |

| ------------------------- | -------------------------------------- | ----------------- |

| `prod-docker-host` / `DCMP_PROD_DOCKER_HOST`        | Docker Host for `production` env (ex: `ssh://docker@docker-host-for-prod:2375`) | _none_ (disabled) |

| ------------------------- |---------------------------------------------------------------------------------------------------------------------| ----------------- |

| `prod-docker-host` / `DCMP_PROD_DOCKER_HOST`        | Docker Host for `production` env (ex: `ssh://user@docker-host-for-prod`)                                        | _none_ (disabled) |

| :lock: `DCMP_PROD_SSH_PRIVATE_KEY` | `production` env specific SSH key to use when connecting to Docker Host over SSH                                    | `$DCMP_SSH_PRIVATE_KEY` |

| `prod-app-name` / `DCMP_PROD_APP_NAME`       | Application name for `production` env                                                                               | `$DCMP_BASE_APP_NAME` |

| `prod-environment-url` / `DCMP_PROD_ENVIRONMENT_URL`| The production environment url _(only define for static environment URLs declaration and if different from default)_ | `$DCMP_ENVIRONMENT_URL` |