Move uncategorised out of docs for now

uncategorised/coop-cloud/working.md

@@ -0,0 +1,97 @@
+# Working with Docker Swarm
+
+## Set up remote context
+
+You can use `docker context` to run Docker command-line commands and have them
+point to the Docker API end-point on a remote host.
+
+This means you can run commands locally and control the remote swarm easily
+(e.g. you run `docker ps` and instead of seeing container on your `localhost`
+you see them on `swarm.autonomic.zone`). This allows to do remote deployments
+manually, filter logs, clean-up containers etc.
+
+!!! note "This is optional!"
+If you like, you can SSH to a swarm server, [install `docker-compose`](https://docs.docker.com/compose/install/#install-compose-on-linux-systems), and run normal Docker commands instead.
+
+Here are the 3 steps to set this up.
+
+1. Create the remote docker context locally.
+
+   ```bash
+   # .envrc.sample
+   export PASSWORD_STORE_DIR=$(pwd)/../infrastructure/credentials/password-store
+   ```
+
+   ```bash
+   $ cp .envrc.sample .envrc
+   $ direnv allow  # ensure password store works
+   $ mkdir -vp ~/.docker/swarm.autonomic.zone && \
+     pass show docker/swarm.autonomic.zone/ca.pem > ~/.docker/swarm.autonomic.zone/ca.pem && \
+     pass show docker/swarm.autonomic.zone/cert.pem > ~/.docker/swarm.autonomic.zone/cert.pem && \
+     pass show docker/swarm.autonomic.zone/key.pem > ~/.docker/swarm.autonomic.zone/key.pem
+   $ docker context create swarm.autonomic.zone --docker \
+     "host=tcp://swarm.autonomic.zone:2376,ca=$HOME/.docker/swarm.autonomic.zone/ca.pem,cert=$HOME/.docker/swarm.autonomic.zone/cert.pem,key=$HOME/.docker/swarm.autonomic.zone/key.pem"
+   $ docker context use swarm.autonomic.zone
+   ```
+
+2. Deploy the application to the remote docker context.
+
+(Assuming you're in, say, the [git.autonomic.zone](https://git.autonomic.zone/autonomic-cooperative/git.autonomic.zone) repository)
+
+```bash
+$ docker stack ls
+$ docker stack deploy -c compose.yml gitea
+```
+
+You can track logs via `docker service logs gitea_gitea`.
+
+3. Switch back to your local context.
+
+```
+$ docker context use default
+```
+
+## Useful concepts & commands
+
+Each app is a **stack**, e.g. `drone` (`docker stack ls`), which creates one or
+more **services**, e.g. `drone_drone` (`docker service ls`), each of which has one or more
+**containers** e.g. `drone_drone.1.czq919syweq23x07whj38pb96` (`docker container ls`). All of this is defined in a `docker-compose.yml` file.
+
+Containers are built from **images**, e.g. `nginx:stable`, optionally using a
+`Dockerfile` to add extra commands or resources.
+
+### Secrets
+
+Most apps will need secret values (like API keys), which Docker can store securely using `docker secret`.
+
+As a failsafe, and to help debugging, we also store secrets in `pass`.
+
+You can generate a password, store it to Docker, and save it to `pass` in one
+step using something like this:
+
+```
+pwgen -n 32 1 | tee \
+  >(docker secret create "APP_SECRET_v1" -)
+  >(pass insert -m hosts/HOSTNAME/APP/SECRET)
+```
+
+Use `docker secrets ls` to see the names of all secrets defined in the current
+context, and `docker secrets rm <NAME>` to remove one if you need to reset it.
+
+## Troubleshooting
+
+If a service is trying to start, but you don't see anything in `docker service logs ...`, then try `docker service ps --no-trunc`, which will show you errors
+during container initialisation.
+
+If you still don't see anything there, log into the swarm server and check the
+Docker logs:
+
+```
+sudo journalctl -u docker.service | tail -n 50
+```
+
+## Investigating persistent journald logs
+
+See [systemd-journald
+docs](https://docs.autonomic.zone/coop-cloud/logging-with-systemd-journald/)
+for more information on the systemd journal logging setup.