From 7da422e23911862571df11edda9f001c4d45984c Mon Sep 17 00:00:00 2001 From: Lev Vereshchagin Date: Fri, 17 Dec 2021 14:10:24 +0300 Subject: [PATCH] Add docs for images and compose files --- README.md | 5 +--- docs/images-and-compose-files.md | 45 ++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 4 deletions(-) create mode 100644 docs/images-and-compose-files.md diff --git a/README.md b/README.md index b5589758..964d2e9c 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,7 @@ We have baseline for developing in VSCode devcontainer with [frappe/bench](https # Production -We provide simple and intuitive production setup with prebuilt Frappe and ERPNext images and compose files. To learn more about those, follow the docs: - -- [images](docs/images.md), -- [compose files](docs/compose-files.md). +We provide simple and intuitive production setup with prebuilt Frappe and ERPNext images and compose files. To learn more about those, [read the docs](docs/images-and-compose-files.md). Also, there's docs to help with deployment: diff --git a/docs/images-and-compose-files.md b/docs/images-and-compose-files.md new file mode 100644 index 00000000..913b7c15 --- /dev/null +++ b/docs/images-and-compose-files.md @@ -0,0 +1,45 @@ +# Images + +There's 4 images that you can find in `/build` directory: + +- `bench`. It is used for development. [Learn more how to start development](../development/README.md). +- `nginx`. This image contains JS and CSS assets. Container using this image also routes incoming requests using [nginx](https://www.nginx.com). +- `socketio`. Container using this image processes realtime websocket requests using [Socket.IO](https://socket.io). +- `worker`. Multi-purpose Python backend. Runs [Werkzeug server](https://werkzeug.palletsprojects.com/en/2.0.x/) with [gunicorn](https://gunicorn.org), queues (via `bench worker`), or schedule (via `bench schedule`). + +> `nginx`, `socketio` and `worker` images — everything we need to be able to run all processes that Frappe framework requires (take a look at [Bench Procfile reference](https://frappeframework.com/docs/v13/user/en/bench/resources/bench-procfile)). We follow [Docker best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#decouple-applications) and split these processes to different containers. + +> ERPNext images don't have their own Dockerfiles. We use [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) and [Docker Buildx](https://docs.docker.com/engine/reference/commandline/buildx/) to reuse as much things as possible and make are builds more efficient. + +# Compose files + +After building the images we have to run the containers. The best and simplest way to do this is to use [compose files](https://docs.docker.com/compose/compose-file/). + +We have one main compose file, `compose.yaml`. Services described, networking, volumes are also handled there. + +Services that the file contains: + +- `configurator`. Updates `common_site_config.json` so Frappe knows how to access db and redis. It is executed on every `docker-compose up` (and exited immediately). Other services start after this container exits successfully. +- `backend`. [Werkzeug server](https://werkzeug.palletsprojects.com/en/2.0.x/). +- `db`. [MariaDB](https://mariadb.com), can be overwritten with [Postgres](https://www.postgresql.org) if you also use `overrides/compose.postgres.yaml`. +- `redis`. [Redis](https://redis.io) server with cache, [Socket.IO](https://socket.io) and queues data. +- `frontend`. [nginx](https://www.nginx.com) server that serves JS/CSS assets and routes incoming requests. +- `proxy`. [Traefik](https://traefik.io/traefik/) proxy. It is here for complicated setups or HTTPS override (with `overrides/compose.https.yaml`). +- `websocket`. Node server that runs [Socket.IO](https://socket.io). +- `queue-short`, `queue-default`, `queue-long`. Python servers that run job queues using [rq](https://python-rq.org). +- `scheduler`. Python server that runs tasks on schedule using [schedule](https://schedule.readthedocs.io/en/stable/). + +Also, we have several [overrides](https://docs.docker.com/compose/extends/). + +- `overrides/compose.erpnext.yaml`. Replaces all Frappe images with ERPNext ones. ERPNext images are built on top of Frappe ones, so it is safe to replace them. +- `overrides/compose.https.yaml`. Automatically sets up Let's Encrypt certificate and redirects all requests to directed to http, to https. +- `overrides/compose.postgres.yaml`. Replaces `db` service's image from MariaDB to Postgres. Note that ERPNext currently doesn't support Postgres. + +It is quite simple to run overrides. All we need to do is to specify compose files that should be used by docker-compose. For example, we want ERPNext: + +```bash +# Point to main compose file (compose.yaml) and add one more. +docker-compose -f compose.yaml -f overrides/compose.erpnext.yaml +``` + +That's it! Of course, we also have to setup `.env` before all of that, but that's not the point.