Compose: notes on logging and scaling

compose/README.md

@@ -5,6 +5,8 @@
 - [Installation](#installation)
 - [Web UIs](#web-uis)
 - [Source code auto-reloading](#source-code-auto-reloading)
+- [Logs](#logs)
+- [Scaling](#scaling)
 - [Ports](#ports)
 - [Cleaning up](#cleaning-up)
 - [Troubleshooting](#troubleshooting)
@@ -16,6 +18,9 @@ This Archivematica environment is based on Docker Compose and it is specifically
 **designed for developers**. Compose can be used in production but that is
 beyond the scope of this recipe.
 
+We use Docker Compose heavily so it's important that you're familiar with it.
+Please read the [documentation](https://docs.docker.com/compose/reference/overview/).
+
 ## Requirements
 
 Ansible, docker-py, Docker, Docker Compose, git, make.
@@ -69,6 +74,36 @@ container is using the newest image, e.g.:
 
     $ docker-compose up -d --force-recreate --build --no-deps archivematica-mcp-server
 
+## Logs
+
+In recent versions of Archivematica we've changed the logging configuration so
+the log events are sent to the standard streams. This is a common practice
+because it makes much easier to aggregate the logs generated by all the
+replicas that we may be deploying of our services across the cluster.
+
+Docker Compose aggregates the logs for us so you can see everything from one
+place. Some examples:
+
+- `docker-compose logs -f`
+- `docker-compose logs -f archivematica-storage-service`
+- `docker-compose logs -f nginx archivematica-dashboard`
+
+## Scaling
+
+With Docker Compose we can run as many containers as we want for a service,
+e.g. by default we only provision a single replica of the
+`archivematica-mcp-client` service but nothing stops you from running more:
+
+    $ docker-compose up -d --scale archivematica-mcp-client=3
+
+We still have one service but three containers. Let's verify that the workers
+are connected to Gearman:
+
+    $ echo workers | socat - tcp:127.0.0.1:62004,shut-none | grep "_v0.0" | awk '{print $2}' - | sort -u
+    172.19.0.15
+    172.19.0.16
+    172.19.0.17
+
 ## Ports
 
 | Service                                 | Container port | Host port   |