frappe_docker/docs/images-and-compose-files.md

Images

There's 4 images that you can find in /build directory:

• bench. It is used for development. Learn more how to start development.
• nginx. This image contains JS and CSS assets. Container using this image also routes incoming requests using nginx.
• socketio. Container using this image processes realtime websocket requests using Socket.IO.
• worker. Multi-purpose Python backend. Runs Werkzeug server with gunicorn, 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). We follow Docker best practices and split these processes to different containers.

ERPNext images don't have their own Dockerfiles. We use multi-stage builds and Docker 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.

We have one main compose file, compose.yaml. Services described, networking, volumes are also handled there.

Services

All services are described in compose.yaml

• 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.
• db. MariaDB, can be overwritten with Postgres if you also use overrides/compose.postgres.yaml.
• redis. Redis server with cache, Socket.IO and queues data.
• frontend. nginx server that serves JS/CSS assets and routes incoming requests.
• proxy. Traefik proxy. It is here for complicated setups or HTTPS override (with overrides/compose.https.yaml).
• websocket. Node server that runs Socket.IO.
• queue-short, queue-default, queue-long. Python servers that run job queues using rq.
• scheduler. Python server that runs tasks on schedule using schedule.

Also, we have several overrides.

• 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:

# 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.

Configuration

We use environment variables to configure our setup. docker-compose uses variables from .env file. To get started, copy example.env to .env.

FRAPPE_VERSION

Frappe framework release. You can find all releases here.

DB_PASSWORD

Password for MariaDB (or Postgres) database.

ERPNEXT_VERSION

ERPNext release. This variable is required if you use ERPNext override.

LETSENCRYPT_EMAIL

Email that used to register https certificate. This one is required only if you use HTTPS override.

FRAPPE_SITE_NAME_HEADER

This environment variable is not required. Default value is $$host which resolves site by host. For example, if your host is example.com, site's name should be example.com, or if host is 127.0.0.1 (local debugging), it should be 127.0.0.1 This variable allows to override described behavior. Let's say you create site named mysite and do want to access it by 127.0.0.1 host. Than you would set this variable to mysite.