Skip to content
Snippets Groups Projects
Commit e99528a2 authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

Merge branch 'initial' into 'main' 

initial docker-compose template

See merge request to-be-continuous/docker-compose!2
parents 86d0d6c7 df084959
Branches
Tags
No related merge requests found
Expand all Show whitespace changes
Inline Side-by-side
README.md
+ 153
− 58
View file @ e99528a2
...@@ -19,9 +19,9 @@ include: ...@@ -19,9 +19,9 @@ include:
inputs: inputs:
# ⚠ this is only an example # ⚠ this is only an example
base-app-name: wonderapp base-app-name: wonderapp
review-project: "prj-12345" # enable review env review-docker-host: "ssh://docker@192.168.64.5:2375" # enable review env
staging-project: "prj-12345" # enable staging env staging-docker-host: "ssh://docker@192.168.64.6:2375" # enable staging env
prod-project: "prj-12345" # enable production env prod-docker-host: "ssh://docker@192.168.64.7:2375" # enable production env
``` ```
### Use as a CI/CD template (legacy) ### Use as a CI/CD template (legacy)
...@@ -39,9 +39,9 @@ variables: ...@@ -39,9 +39,9 @@ variables:
# 2: set/override template variables # 2: set/override template variables
# ⚠ this is only an example # ⚠ this is only an example
DCMP_BASE_APP_NAME: wonderapp DCMP_BASE_APP_NAME: wonderapp
DCMP_REVIEW_PROJECT: "prj-12345" # enable review env DCMP_REVIEW_DOCKER_HOST: "ssh://docker@192.168.64.5:2375" # enable review env
DCMP_STAGING_PROJECT: "prj-12345" # enable staging env DCMP_STAGING_DOCKER_HOST: "ssh://docker@192.168.64.6:2375" # enable staging env
DCMP_PROD_PROJECT: "prj-12345" # enable production env DCMP_PROD_DOCKER_HOST: "ssh://docker@192.168.64.7:2375" # enable production env
``` ```
## Understand ## Understand
...@@ -93,18 +93,22 @@ You're free to enable whichever or both, and you can also choose your deployment ...@@ -93,18 +93,22 @@ You're free to enable whichever or both, and you can also choose your deployment
### Supported authentication methods ### Supported authentication methods
The Docker Compose template supports the following authentication methods: 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:
* TODO (document) * `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`),
* :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 ### Deployment context variables
In order to manage the various deployment environments, this template provides a couple of **dynamic variables** In order to manage the various deployment environments, this template provides a couple of **dynamic variables**
that you might use in your hook scripts, deployment manifests and other deployment resources: that you might use in your hook scripts or [Docker Compose files](https://docs.docker.com/compose/compose-application-model/#the-compose-file):
* `${environment_type}`: the current deployment environment type (`review`, `integration`, `staging` or `production`) * `${environment_type}`: the current deployment environment type (`review`, `integration`, `staging` or `production`)
* `${environment_name}`: a generated application name to use for the current deployment environment (ex: `myapp-review-fix-bug-12` or `myapp-staging`) - _details below_ * `${environment_name}`: a generated application name to use for the current deployment environment (ex: `myapp-review-fix-bug-12` or `myapp-staging`) - _details below_
> :information_source: the `${environment_name}` is used by the Docker Compose template as the [Docker Compose project name](https://docs.docker.com/compose/project-name/).
#### Generated environment name #### Generated environment name
The `${environment_name}` variable is generated to designate each deployment environment with a unique and meaningful application name. The `${environment_name}` variable is generated to designate each deployment environment with a unique and meaningful application name.
...@@ -131,38 +135,116 @@ Examples (with an application's base name `myapp`): ...@@ -131,38 +135,116 @@ Examples (with an application's base name `myapp`):
### Deployment and cleanup ### Deployment and cleanup
> TODO: explain here the supported techniques to deploy and cleanup the environments. The Docker Compose template requires you to provide:
* a _required_ [Compose file](https://docs.docker.com/compose/compose-application-model/#the-compose-file) that implements your application deployment and cleanup,
* _optional_ [`.override.` Compose files](https://docs.docker.com/compose/multiple-compose-files/merge/) defining common and/or per-env override,
* _optional_ [dotenv files](https://docs.docker.com/compose/environment-variables/env-file/) defining common and/or per-env configuration,
* _optional_ hook scripts (shell) to implement logic that can't be implemented with Docker Compose.
#### Compose files lookup strategy
Unless you have explicitly set the [`COMPOSE_FILES`](https://docs.docker.com/compose/environment-variables/envvars/#compose_file) variable, the Docker Compose template will handle it and
implement the following [Compose file(s)](https://docs.docker.com/compose/compose-application-model/#the-compose-file) lookup strategy:
| Lookup order | Compose file | Additional `.override.` files (optional) |
|:------------:|--------------|------------------------------------------------------------------------------------------------------------------------------------------|
| 1. | **environment specific** (`compose-${environment_type}.yaml`) | **environment specific** override (`compose-${environment_type}.override.yaml`) |
| 2. | **default** (`compose.yaml`) | 1. **default** override (`compose.override.yaml`)<br/>2. **environment specific** override (`compose-${environment_type}.override.yaml`) |
> :information_source: Important:
> >
> You should also explained clearly what is expected from the template user and what is the lookup policy in case the template > * Compose file base name `docker-compose` is also supported as an alternative to `compose`,
> implements one. > * Compose file extension `.yml` is also supported as an alternative to `.yaml`,
> * `.override.` files must match the same base name (`compose` or `docker-compose`) and extension (`yaml` or `yml`) as the found Compose file.
Examples with different combinations of files:
<table>
<thead>
<tr>
<th>Files in your project</th>
<th>Compose files for Review</th>
<th>Compose files for Integration</th>
<th>Compose files for Staging</th>
<th>Compose files for Production</th>
</tr>
</thead>
<tfoot>
<tr>
<td>- <code>compose.yaml</code></td>
<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 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 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>
<tr>
<td>- <code>compose.yml</code><br/>- <code>compose.override.yml</code><br/>- <code>compose-review.override.yml</code><br/>- <code>compose-production.yml</code></td>
<td align=center><code>compose.yml</code> + <code>compose.override.yml</code> + <code>compose-review.override.yml</code> (merged)</td>
<td colspan="2" align=center><code>compose.yml</code>+ <code>compose.override.yml</code> (merged)</td>
<td align=center><code>compose-production.yml</code></td>
</tr>
</tfoot>
<tbody>
</tbody>
</table>
#### Dotenv files lookup strategy
Unless you have explicitly set the [`COMPOSE_ENV_FILES`](https://docs.docker.com/compose/environment-variables/envvars/#compose_env_files) variable, the Docker Compose template will handle it
and implement the following [dotenv files](https://docs.docker.com/compose/environment-variables/env-file/) lookup strategy:
1. a `.env` file defining defaults for all environments,
2. a `${environment_type}.env` file that might redefine or override defaults for a specific environment (e.g. `staging.env`).
#### Deployment
The **deployment** is processed as follows by the template:
1. _optionally_ executes the `pre-compose-up.sh` script found in your project to perform pre-deployment stuff (for e.g. create required services),
2. runs [`docker-compose up`](https://docs.docker.com/reference/cli/docker/compose/up/),
3. _optionally_ executes the `post-compose-up.sh` script found in your project to perform post-deployment stuff,
> :information_source: Important:
> >
> Example: > * Compose files, dotenv files and hook scripts are searched in the `$DCMP_SCRIPTS_DIR` directory (configurable),
> * Hook scripts need to be executable; you can add the execution flag with `git update-index --chmod=+x pre-compose-up.sh`.
The Docker Compose template requires you to provide a shell script that fully implements your application #### Cleanup
deployment and cleanup using the `docker-compose` CLI and all other tools available in the selected Docker image.
The deployment script is searched as follows: The **cleanup** is processed as follows by the template:
1. look for a specific `dcmp-deploy-$environment_type.sh` in the `$DCMP_SCRIPTS_DIR` directory in your project (e.g. `dcmp-deploy-staging.sh` for staging environment), 1. _optionally_ executes the `pre-compose-down.sh` script found in your project to perform pre-cleanup stuff,
2. if not found: look for a default `dcmp-deploy.sh` in the `$DCMP_SCRIPTS_DIR` directory in your project, 2. runs [`docker-compose down`](https://docs.docker.com/reference/cli/docker/compose/down/),
3. if not found: the deployment job will fail. 3. _optionally_ executes the `post-compose-down.sh` script found in your project to perform post-cleanup stuff,
The cleanup script is searched as follows: > :information_source: Important:
>
> * Compose files, dotenv files and hook scripts are searched in the `$DCMP_SCRIPTS_DIR` directory (configurable),
> * Hook scripts need to be executable; you can add the execution flag with `git update-index --chmod=+x pre-compose-up.sh`.
1. look for a specific `dcmp-cleanup-$environment_type.sh` in the `$DCMP_SCRIPTS_DIR` directory in your project (e.g. `dcmp-cleanup-staging.sh` for staging environment), #### Using Variables
2. if not found: look for a default `dcmp-cleanup.sh` in the `$DCMP_SCRIPTS_DIR` directory in your project,
3. if not found: the cleanup job will fail.
> :information_source: Your deployment (and cleanup) scripts have to be able to cope with various environments, each with different application names, exposed routes, settings, ... Your deployment (and cleanup) scripts have to be able to cope with various environments, each with different application names, exposed routes, settings, ...
> Part of this complexity can be handled by the lookup policies described above (ex: one script per env) and also by using available environment variables: Part of this complexity can be handled by the lookup strategies described above (ex: one file per env) and also by using available environment variables:
>
> 1. [deployment context variables](#deployment-context-variables) provided by the template: 1. [deployment context variables](#deployment-context-variables) provided by the template:
> * `${environment_type}`: the current environment type (`review`, `integration`, `staging` or `production`) * `${environment_type}`: the current environment type (`review`, `integration`, `staging` or `production`)
> * `${environment_name}`: the application name to use for the current environment (ex: `myproject-review-fix-bug-12` or `myproject-staging`) * `${environment_name}`: the application name to use for the current environment (ex: `myproject-review-fix-bug-12` or `myproject-staging`)
> * `${hostname}`: the environment hostname, extracted from the current environment url (after late variable expansion - see below) * `${hostname}`: the environment hostname, extracted from the current environment url (after late variable expansion - see below)
> 2. any [GitLab CI variable](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) 2. any [GitLab CI variable](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)
> 3. any [custom variable](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project) 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) (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/)
using the appropriate [interpolation syntax](https://docs.docker.com/compose/environment-variables/env-file/#interpolation).
### Environments URL management ### Environments URL management
...@@ -193,7 +275,7 @@ The **static way** can be implemented simply by setting the appropriate configur ...@@ -193,7 +275,7 @@ The **static way** can be implemented simply by setting the appropriate configur
> DCMP_REVIEW_ENVIRONMENT_URL: "https://wonderapp-review.nonprod.acme.domain/%{environment_name}" > DCMP_REVIEW_ENVIRONMENT_URL: "https://wonderapp-review.nonprod.acme.domain/%{environment_name}"
> ``` > ```
To implement the **dynamic way**, your deployment script shall simply generate a `environment_url.txt` file in the working directory, containing only To implement the **dynamic way**, your post deployment hook script shall simply generate a `environment_url.txt` file in the working directory, containing only
the dynamically generated url. When detected by the template, it will use it as the newly deployed environment url. the dynamically generated url. When detected by the template, it will use it as the newly deployed environment url.
### Deployment output variables ### Deployment output variables
...@@ -206,7 +288,7 @@ Each deployment job produces _output variables_ that are propagated to downstrea ...@@ -206,7 +288,7 @@ Each deployment job produces _output variables_ that are propagated to downstrea
Those variables may be freely used in downstream jobs (for instance to run acceptance tests against the latest deployed environment). Those variables may be freely used in downstream jobs (for instance to run acceptance tests against the latest deployed environment).
You may also add and propagate your own custom variables, by pushing them to the `docker-compose.env` file in your [deployment scripts or hooks](#deployment-and-cleanup). You may also add and propagate your own custom variables, by pushing them to the `docker-compose.out.env` file in your [deployment scripts or hooks](#deployment-and-cleanup).
## Configuration reference ## Configuration reference
...@@ -214,7 +296,7 @@ You may also add and propagate your own custom variables, by pushing them to the ...@@ -214,7 +296,7 @@ You may also add and propagate your own custom variables, by pushing them to the
Here are some advices about your **secrets** (variables marked with a :lock:): Here are some advices about your **secrets** (variables marked with a :lock:):
1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project): 1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-docker-host):
* [**masked**](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable) to prevent them from being inadvertently * [**masked**](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable) to prevent them from being inadvertently
displayed in your job logs, displayed in your job logs,
* [**protected**](https://docs.gitlab.com/ee/ci/variables/#protected-cicd-variables) if you want to secure some secrets * [**protected**](https://docs.gitlab.com/ee/ci/variables/#protected-cicd-variables) if you want to secure some secrets
...@@ -230,28 +312,30 @@ The Docker Compose template uses some global configuration used throughout all j ...@@ -230,28 +312,30 @@ The Docker Compose template uses some global configuration used throughout all j
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
| ------------------------ | -------------------------------------- | ----------------- | | ------------------------ | -------------------------------------- | ----------------- |
| `image` / `DCMP_IMAGE` | the Docker image used to run Docker Compose CLI commands | `registry.hub.docker.com/docker-compose:latest` | | `image` / `DCMP_IMAGE` | the Docker image used to run Docker Compose CLI commands | `registry.hub.docker.com/library/docker:latest` |
| `cmd` / `DCMP_CMD` | The docker compose command (`docker compose` or `docker-compose`) | _none_ (auto) |
| `base-app-name` / `DCMP_BASE_APP_NAME`| Base application name | `$CI_PROJECT_NAME` ([see GitLab doc](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)) | | `base-app-name` / `DCMP_BASE_APP_NAME`| Base application name | `$CI_PROJECT_NAME` ([see GitLab doc](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)) |
| `api-url` / `DCMP_API_URL` | Default Docker Compose API url | _none_ |
| :lock: `DCMP_API_TOKEN` | Default Docker Compose API token | _none_ |
| `environment-url` / `DCMP_ENVIRONMENT_URL`| Default environments url _(only define for static environment URLs declaration)_<br/>_supports late variable expansion (ex: `https://%{environment_name}.docker-compose.acme.com`)_ | _none_ | | `environment-url` / `DCMP_ENVIRONMENT_URL`| Default environments url _(only define for static environment URLs declaration)_<br/>_supports late variable expansion (ex: `https://%{environment_name}.docker-compose.acme.com`)_ | _none_ |
| `scripts-dir` / `DCMP_SCRIPTS_DIR` | Directory where deploy & cleanup scripts are located | `.` _(root project dir)_ | | `scripts-dir` / `DCMP_SCRIPTS_DIR`| Directory where Compose files, dotenv files and hook scripts are located | `.` _(root project dir)_ |
| `up-opts` / `DCMP_UP_OPTS` | [`compose up` options](https://docs.docker.com/reference/cli/docker/compose/up/#options) | `--no-build --remove-orphans --wait --wait-timeout 180` |
| `down-opts`/ `DCMP_DOWN_OPTS` | [`compose down` options](https://docs.docker.com/reference/cli/docker/compose/down/#options) | `--volumes --remove-orphans --rmi all` |
| :lock: `DCMP_SSH_PRIVATE_KEY` | Default SSH key to use when connecting to Docker hosts over SSH (can be overridden per env) | _none_ |
| `ssh-known-hosts` / `DCMP_SSH_KNOWN_HOSTS` | SSH `known_hosts` (file or text variable) | _none_ |
### Review environments configuration ### Review environments configuration
Review environments are dynamic and ephemeral environments to deploy your _ongoing developments_ (a.k.a. _feature_ or Review environments are dynamic and ephemeral environments to deploy your _ongoing developments_ (a.k.a. _feature_ or
_topic_ branches). _topic_ branches).
They are **disabled by default** and can be enabled by setting the `DCMP_REVIEW_PROJECT` variable (see below). They are **disabled by default** and can be enabled by setting the `DCMP_REVIEW_DOCKER_HOST` variable (see below).
Here are variables supported to configure review environments: Here are variables supported to configure review environments:
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
| ------------------------ | -------------------------------------- | ----------------- | | ------------------------ | -------------------------------------- | ----------------- |
| `review-project` / `DCMP_REVIEW_PROJECT` | Project ID for `review` env | _none_ (disabled) | | `review-docker-host` / `DCMP_REVIEW_DOCKER_HOST` | Docker Host for `review` env (ex: `ssh://docker@docker-host-for-review:2375`) | _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-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-api-url` / `DCMP_REVIEW_API_URL` | API url for `review` env _(only define to override default)_ | `$DCMP_API_URL` |
| :lock: `DCMP_REVIEW_API_TOKEN` | API token for `review` env _(only define to override default)_ | `$DCMP_API_TOKEN` |
| `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` | | `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` |
| `review-autostop-duration` / `DCMP_REVIEW_AUTOSTOP_DURATION`| The amount of time before GitLab will automatically stop `review` environments | `4 hours` | | `review-autostop-duration` / `DCMP_REVIEW_AUTOSTOP_DURATION`| The amount of time before GitLab will automatically stop `review` environments | `4 hours` |
...@@ -259,16 +343,15 @@ Here are variables supported to configure review environments: ...@@ -259,16 +343,15 @@ Here are variables supported to configure review environments:
The integration environment is the environment associated to your integration branch (`develop` by default). The integration environment is the environment associated to your integration branch (`develop` by default).
It is **disabled by default** and can be enabled by setting the `DCMP_INTEG_PROJECT` variable (see below). It is **disabled by default** and can be enabled by setting the `DCMP_INTEG_DOCKER_HOST` variable (see below).
Here are variables supported to configure the integration environment: Here are variables supported to configure the integration environment:
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
| ------------------------ | -------------------------------------- | ----------------- | | ------------------------ | -------------------------------------- | ----------------- |
| `integ-project` / `DCMP_INTEG_PROJECT` | Project ID for `integration` env | _none_ (disabled) | | `integ-docker-host` / `DCMP_INTEG_DOCKER_HOST` | Docker Host for `integration` env (ex: `ssh://docker@docker-host-for-integ:2375`) | _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-app-name` / `DCMP_INTEG_APP_NAME` | Application name for `integration` env | `${DCMP_BASE_APP_NAME}-integration` |
| `integ-api-url` / `DCMP_INTEG_API_URL` | API url for `integration` env _(only define to override default)_ | `$DCMP_API_URL` |
| :lock: `DCMP_INTEG_API_TOKEN` | API token for `integration` env _(only define to override default)_ | `$DCMP_API_TOKEN` |
| `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` | | `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` |
### Staging environment configuration ### Staging environment configuration
...@@ -276,31 +359,43 @@ Here are variables supported to configure the integration environment: ...@@ -276,31 +359,43 @@ Here are variables supported to configure the integration environment:
The staging environment is an iso-prod environment meant for testing and validation purpose associated to your production The staging environment is an iso-prod environment meant for testing and validation purpose associated to your production
branch (`main` or `master` by default). branch (`main` or `master` by default).
It is **disabled by default** and can be enabled by setting the `DCMP_STAGING_PROJECT` variable (see below). It is **disabled by default** and can be enabled by setting the `DCMP_STAGING_DOCKER_HOST` variable (see below).
Here are variables supported to configure the staging environment: Here are variables supported to configure the staging environment:
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
| ------------------------ | -------------------------------------- | ----------------- | | ------------------------ | -------------------------------------- | ----------------- |
| `staging-project` / `DCMP_STAGING_PROJECT` | Project ID for `staging` env | _none_ (disabled) | | `staging-docker-host` / `DCMP_STAGING_DOCKER_HOST` | Docker Host for `staging` env (ex: `ssh://docker@docker-host-for-staging:2375`) | _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-app-name` / `DCMP_STAGING_APP_NAME` | Application name for `staging` env | `${DCMP_BASE_APP_NAME}-staging` |
| `staging-api-url` / `DCMP_STAGING_API_URL` | API url for `staging` env _(only define to override default)_ | `$DCMP_API_URL` |
| :lock: `DCMP_STAGING_API_TOKEN` | API token for `staging` env _(only define to override default)_ | `$DCMP_API_TOKEN` |
| `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` | | `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` |
### Production environment configuration ### Production environment configuration
The production environment is the final deployment environment associated with your production branch (`main` or `master` by default). The production environment is the final deployment environment associated with your production branch (`main` or `master` by default).
It is **disabled by default** and can be enabled by setting the `DCMP_PROD_PROJECT` variable (see below). It is **disabled by default** and can be enabled by setting the `DCMP_PROD_DOCKER_HOST` variable (see below).
Here are variables supported to configure the production environment: Here are variables supported to configure the production environment:
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
| ------------------------- | -------------------------------------- | ----------------- | | ------------------------- | -------------------------------------- | ----------------- |
| `prod-project` / `DCMP_PROD_PROJECT` | Project ID for `production` env | _none_ (disabled) | | `prod-docker-host` / `DCMP_PROD_DOCKER_HOST` | Docker Host for `production` env (ex: `ssh://docker@docker-host-for-prod:2375`) | _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-app-name` / `DCMP_PROD_APP_NAME` | Application name for `production` env | `$DCMP_BASE_APP_NAME` |
| `prod-api-url` / `DCMP_PROD_API_URL` | API url for `production` env _(only define to override default)_ | `$DCMP_API_URL` |
| :lock: `DCMP_PROD_API_TOKEN` | API token for `production` env _(only define to override default)_ | `$DCMP_API_TOKEN` |
| `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` | | `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` |
| `prod-deploy-strategy` / `DCMP_PROD_DEPLOY_STRATEGY`| Defines the deployment to production strategy. One of `manual` (i.e. _one-click_) or `auto`. | `manual` | | `prod-deploy-strategy` / `DCMP_PROD_DEPLOY_STRATEGY`| Defines the deployment to production strategy. One of `manual` (i.e. _one-click_) or `auto`. | `manual` |
### Compose Config job
The Docker Compose template enables running [Compose Config](https://docs.docker.com/reference/cli/docker/compose/config/), thus enabling detection of syntax errors in your Compose or dotenv files.
This job is mapped to the `package-test` stage and is **active** by default.
Here are its parameters:
| Input / Variable | Description | Default value |
| ----------------------- | ----------------------------------------- | ----------------------------- |
| `config-disabled` / `DCMP_CONFIG_DISABLED` | Set to `true` to disable `compose config` | _none_ (enabled) |
| `config-opts` / `DCMP_CONFIG_OPTS` | [`compose config` options](https://docs.docker.com/reference/cli/docker/compose/config/#options) | `--quiet` _(to avoid displaying secrets inadvertently)_ |
kicker.json
+ 68
− 63
View file @ e99528a2
...@@ -10,17 +10,13 @@ ...@@ -10,17 +10,13 @@
{ {
"name": "DCMP_IMAGE", "name": "DCMP_IMAGE",
"description": "The Docker image used to run Docker Compose CLI commands - **set the version required by your Docker Compose cluster**", "description": "The Docker image used to run Docker Compose CLI commands - **set the version required by your Docker Compose cluster**",
"default": "registry.hub.docker.com/docker-compose:latest" "default": "registry.hub.docker.com/library/docker:latest"
}, },
{ {
"name": "DCMP_API_URL", "name": "DCMP_CMD",
"type": "url", "description": "The docker compose command (empty means _auto_)",
"description": "Default Docker Compose API url" "values": ["", "docker compose", "docker-compose"],
}, "advanced": true
{
"name": "DCMP_API_TOKEN",
"description": "Default Docker Compose API token",
"secret": true
}, },
{ {
"name": "DCMP_BASE_APP_NAME", "name": "DCMP_BASE_APP_NAME",
...@@ -35,22 +31,60 @@ ...@@ -35,22 +31,60 @@
}, },
{ {
"name": "DCMP_SCRIPTS_DIR", "name": "DCMP_SCRIPTS_DIR",
"description": "Directory where deploy & cleanup scripts are located", "description": "Directory where Compose files, dotenv files and hook scripts are located",
"default": ".", "default": ".",
"advanced": true "advanced": true
},
{
"name": "DCMP_UP_OPTS",
"description": "[`compose up` options](https://docs.docker.com/reference/cli/docker/compose/up/#options)",
"default": "--no-build --remove-orphans --wait --wait-timeout 180"
},
{
"name": "DCMP_DOWN_OPTS",
"description": "[`compose down` options](https://docs.docker.com/reference/cli/docker/compose/down/#options)",
"default": "--volumes --remove-orphans --rmi all"
},
{
"name": "DCMP_SSH_PRIVATE_KEY",
"description": "Default SSH key to use when connecting to Docker hosts over SSH (can be overridden per env)",
"secret": true
},
{
"name": "DCMP_SSH_KNOWN_HOSTS",
"description": "SSH `known_hosts` (file or text variable)"
} }
], ],
"features": [ "features": [
{
"id": "config",
"name": "Compose Config",
"description": "Runs [`compose config`](https://docs.docker.com/reference/cli/docker/compose/config/) to detect errors in your Compose file(s)",
"disable_with": "DCMP_CONFIG_DISABLED",
"variables": [
{
"name": "DCMP_CONFIG_OPTS",
"description": "[`compose config` options](https://docs.docker.com/reference/cli/docker/compose/config/#options)",
"default": "--quiet",
"advanced": true
}
]
},
{ {
"id": "review", "id": "review",
"name": "Review", "name": "Review",
"description": "Dynamic review environments for your topic branches (see GitLab [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/))", "description": "Dynamic review environments for your topic branches (see GitLab [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/))",
"variables": [ "variables": [
{ {
"name": "DCMP_REVIEW_PROJECT", "name": "DCMP_REVIEW_DOCKER_HOST",
"description": "Project ID for `review` env", "description": "Docker Host for `review` env (ex: `ssh://docker@docker-host-for-review:2375`)",
"mandatory": true "mandatory": true
}, },
{
"name": "DCMP_REVIEW_SSH_PRIVATE_KEY",
"description": "`review` env specific SSH key to use when connecting to Docker Host over SSH",
"secret": true
},
{ {
"name": "DCMP_REVIEW_APP_NAME", "name": "DCMP_REVIEW_APP_NAME",
"description": "The application name for `review` env (only define to override default)", "description": "The application name for `review` env (only define to override default)",
...@@ -66,17 +100,6 @@ ...@@ -66,17 +100,6 @@
"type": "url", "type": "url",
"description": "The `review` environments url _(only define for static environment URLs declaration and if different from default)_", "description": "The `review` environments url _(only define for static environment URLs declaration and if different from default)_",
"advanced": true "advanced": true
},
{
"name": "DCMP_REVIEW_API_URL",
"type": "url",
"description": "API url for `review` env _(only define to override default)_",
"advanced": true
},
{
"name": "DCMP_REVIEW_API_TOKEN",
"description": "API token for `review` env (only define to override default)",
"secret": true
} }
] ]
}, },
...@@ -86,10 +109,15 @@ ...@@ -86,10 +109,15 @@
"description": "A continuous-integration environment associated to your integration branch (`develop` by default)", "description": "A continuous-integration environment associated to your integration branch (`develop` by default)",
"variables": [ "variables": [
{ {
"name": "DCMP_INTEG_PROJECT", "name": "DCMP_INTEG_DOCKER_HOST",
"description": "Project ID for `integration` env", "description": "Docker Host for `integration` env (ex: `ssh://docker@docker-host-for-integ:2375`)",
"mandatory": true "mandatory": true
}, },
{
"name": "DCMP_INTEG_SSH_PRIVATE_KEY",
"description": "`integration` env specific SSH key to use when connecting to Docker Host over SSH",
"secret": true
},
{ {
"name": "DCMP_INTEG_APP_NAME", "name": "DCMP_INTEG_APP_NAME",
"description": "The application name for `integration` env (only define to override default)", "description": "The application name for `integration` env (only define to override default)",
...@@ -100,17 +128,6 @@ ...@@ -100,17 +128,6 @@
"type": "url", "type": "url",
"description": "The `integration` environment url _(only define for static environment URLs declaration and if different from default)_", "description": "The `integration` environment url _(only define for static environment URLs declaration and if different from default)_",
"advanced": true "advanced": true
},
{
"name": "DCMP_INTEG_API_URL",
"type": "url",
"description": "API url for `integration` env _(only define to override default)_",
"advanced": true
},
{
"name": "DCMP_INTEG_API_TOKEN",
"description": "API token for `integration` env (only define to override default)",
"secret": true
} }
] ]
}, },
...@@ -120,10 +137,15 @@ ...@@ -120,10 +137,15 @@
"description": "An iso-prod environment meant for testing and validation purpose on your production branch (`main` or `master` by default)", "description": "An iso-prod environment meant for testing and validation purpose on your production branch (`main` or `master` by default)",
"variables": [ "variables": [
{ {
"name": "DCMP_STAGING_PROJECT", "name": "DCMP_STAGING_DOCKER_HOST",
"description": "Project ID for `staging` env", "description": "Docker Host for `staging` env (ex: `ssh://docker@docker-host-for-staging:2375`)",
"mandatory": true "mandatory": true
}, },
{
"name": "DCMP_STAGING_SSH_PRIVATE_KEY",
"description": "`staging` env specific SSH key to use when connecting to Docker Host over SSH",
"secret": true
},
{ {
"name": "DCMP_STAGING_APP_NAME", "name": "DCMP_STAGING_APP_NAME",
"description": "The application name for `staging` env (only define to override default)", "description": "The application name for `staging` env (only define to override default)",
...@@ -134,17 +156,6 @@ ...@@ -134,17 +156,6 @@
"type": "url", "type": "url",
"description": "The `staging` environment url _(only define for static environment URLs declaration and if different from default)_", "description": "The `staging` environment url _(only define for static environment URLs declaration and if different from default)_",
"advanced": true "advanced": true
},
{
"name": "DCMP_STAGING_API_URL",
"type": "url",
"description": "API url for `staging` env _(only define to override default)_",
"advanced": true
},
{
"name": "DCMP_STAGING_API_TOKEN",
"description": "API token for `staging` env (only define to override default)",
"secret": true
} }
] ]
}, },
...@@ -154,10 +165,15 @@ ...@@ -154,10 +165,15 @@
"description": "The production environment", "description": "The production environment",
"variables": [ "variables": [
{ {
"name": "DCMP_PROD_PROJECT", "name": "DCMP_PROD_DOCKER_HOST",
"description": "Project ID for `production` env", "description": "Docker Host for `production` env (ex: `ssh://docker@docker-host-for-prod:2375`)",
"mandatory": true "mandatory": true
}, },
{
"name": "DCMP_PROD_SSH_PRIVATE_KEY",
"description": "`production` env specific SSH key to use when connecting to Docker Host over SSH",
"secret": true
},
{ {
"name": "DCMP_PROD_APP_NAME", "name": "DCMP_PROD_APP_NAME",
"description": "The application name for `production` env (only define to override default)", "description": "The application name for `production` env (only define to override default)",
...@@ -175,17 +191,6 @@ ...@@ -175,17 +191,6 @@
"type": "enum", "type": "enum",
"values": ["manual", "auto"], "values": ["manual", "auto"],
"default": "manual" "default": "manual"
},
{
"name": "DCMP_PROD_API_URL",
"type": "url",
"description": "API url for `production` env _(only define to override default)_",
"advanced": true
},
{
"name": "DCMP_PROD_API_TOKEN",
"description": "API token for `production` env (only define to override default)",
"secret": true
} }
] ]
} }
......
templates/gitlab-ci-docker-compose.yml
+ 414
− 124
View file @ e99528a2
This diff is collapsed.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please to comment