WIP: lots more documentation

doc/docker-compose.md

@@ -0,0 +1,70 @@
+# Working with Docker-Compose Services
+
+The Overleaf toolkit runs Overleaf inside a docker container, plus the
+supporting databases (MongoDB and Redis), in their own containers. All of this
+is orchestrated with `docker-compose`.
+
+Note: for legacy reasons, the main Overleaf container is called `sharelatex`,
+and is based on the `sharelatex/sharelatex` docker image. This is because the
+technology is based on the ShareLaTeX code base, which was merged into Overleaf.
+See [this blog
+post](https://www.overleaf.com/blog/518-exciting-news-sharelatex-is-joining-overleaf)
+for more details. At some point in the future, this will be renamed to match the
+Overleaf naming scheme.
+
+
+## The `bin/docker-compose` Wrapper
+
+The `bin/docker-compose` script is a wrapper around `docker-compose`. It
+loads configuration from the `config/` directory, before invoking
+`docker-compose` with whatever arguments were passed to the script.
+
+You can treat `bin/docker-compose` as a transparent wrapper for the
+`docker-compose` program installed on your machine.
+
+For example, we can check which containers are running with the following:
+
+```
+$ bin/docker-compose ps
+```
+
+
+## Convenience Helpers
+
+In addition to `bin/docker-compose`, the toolkit also provides a collection of
+convenient scripts to automate common tasks:
+
+- `bin/up`: shortcut for `bin/docker-compose up`
+- `bin/start`: shortcut for `bin/docker-compose start`
+- `bin/stop`: shortcut for `bin/docker-compose stop`
+- `bin/shell`: starts a shell inside the main container
+
+
+## Architecture
+
+Inside the overleaf container, the Overleaf software runs as a set of micro-services, managed by `runit`. Some of the more interesting files inside the container are:
+
+- `/etc/service/`: initialisation files for the microservices
+- `/etc/sharelatex/settings.coffee`: unified settings file for the microservices
+- `/var/log/sharelatex/`: logs for each microservice
+- `/var/www/sharelatex/`: code for the various microservices
+- `/var/lib/sharelatex/`: the mount-point for persistent data (corresponds to the directory indicated by `SHARELATEX_DATA_PATH` on the host)
+
+
+## The MongoDB and Redis Containers
+
+Overleaf dedends on two external databases: MongoDB and Redis. By default, the toolkit will provision a container for each of these databases, in addition to the Overleaf container, for a total of three docker containers.
+
+If you would prefer to connect to an existing MongoDB or Redis instance, you can do so by setting the appropriate settings in  the [overleaf.rc](./overleaf-rc.md) configuration file.
+
+
+## Viewing Individual Micro-Service Logs
+
+The `bin/logs` script allows you to select individual log streams from inside the overleaf container.
+For example, if you want to see just the logs for the `web` and `clsi` (compiler) micro-services, run:
+
+```
+$ bin/logs -f web clsi
+```
+
+See the output of `bin/logs --help` for more options.