From d952592f7bf886a8443343243cc8d64ebfc26802 Mon Sep 17 00:00:00 2001
From: Dirk de Visser <github@dirkdevisser.nl>
Date: Sun, 10 Sep 2023 13:19:37 +0200
Subject: [PATCH] chore(docs): add docs on the Docker integrations for the new
 CLI

---
 docs/docs/integrations/docker.md | 54 +++++++++++++++++++++++++++++---
 1 file changed, 50 insertions(+), 4 deletions(-)

diff --git a/docs/docs/integrations/docker.md b/docs/docs/integrations/docker.md
index 5b0aa38181..b39d0e9b91 100644
--- a/docs/docs/integrations/docker.md
+++ b/docs/docs/integrations/docker.md
@@ -1,5 +1,51 @@
-# Docker
+# Docker integration
 
-- `compas init docker`
-- Config file
-- Resetting the containers
+Most of the time your application requires external services. Compas supports
+automatically spinning up those external services via
+[Docker](https://docs.docker.com/).
+
+## Getting started
+
+The docker integration is not enabled by default. You can run the following
+command or apply the config changes below manually.
+
+```shell
+compas init docker
+```
+
+This creates or updates the Compas config file in `config/compas.json` with the
+following contents:
+
+```json
+{
+  "dockerContainers": {
+    "compas-postgres-15": {
+      "createArguments": "-e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e PGDATA=/var/lib/postgresql/data/pgdata -v compas-postgres-15:/var/lib/postgresql/data/pgdata -p 5432:5432",
+      "image": "postgres:15"
+    }
+  }
+}
+```
+
+## Config
+
+Each container definition has the following properties:
+
+- The image name, in the above example 'compas-postgres-15'. This name should
+  either be unique over all your projects, or the container is reused across
+  projects that specify the same name. This may be the desired behavior if you
+  work on multiple projects that share the same set of services.
+- `createArguments`: Arguments to pass to the `docker create` command. See the
+  [Docker documentation](https://docs.docker.com/engine/reference/commandline/create/)
+  for more information. The `--name` argument and image are provided by Compas.
+- `image`: The image to create the container from. Anything that Docker supports
+  works. It is advised to develop against the same versions as your production
+  environment will have.
+
+## Limitations
+
+- Compas currently does not have any behavior to automatically stop containers.
+- The Docker containers will still run in the background even though you stopped
+  the development CLI. This could cause conflicts with for example used ports
+  when you start working on a different project. You can stop containers with
+  `docker stop $name` and remove them with `docker rm $name`.