admin/frappe_docker
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs: README and docs

Browse Source
This commit is contained in:
Revant Nandgaonkar
2021-12-26 13:38:51 +05:30
parent 23b0ff6454
commit 25aa226d8f
16 changed files with 265 additions and 660 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -23,7 +23,7 @@ We provide simple and intuitive production setup with prebuilt Frappe and ERPNex
Also, there's docs to help with deployment: Also, there's docs to help with deployment:
- [on single server](docs/single-server.md), - [setup options](docs/setup-options.md),
- in cluster: - in cluster:
- [Docker Swarm](docs/docker-swarm.md), - [Docker Swarm](docs/docker-swarm.md),
- [Kubernetes (frappe/helm)](https://helm.erpnext.com), - [Kubernetes (frappe/helm)](https://helm.erpnext.com),

49
compose.yaml
View File

@@ -14,15 +14,13 @@ services:
<<: *backend_defaults <<: *backend_defaults
command: configure.py command: configure.py
environment: environment:
DB_HOST: db DB_HOST: ${DB_HOST}
DB_PORT: 3306 DB_PORT: ${DB_PORT}
REDIS_CACHE: redis:6379/0 REDIS_CACHE: ${REDIS_CACHE}
REDIS_QUEUE: redis:6379/1 REDIS_QUEUE: ${REDIS_QUEUE}
REDIS_SOCKETIO: redis:6379/2 REDIS_SOCKETIO: ${REDIS_SOCKETIO}
SOCKETIO_PORT: 9000 SOCKETIO_PORT: 9000
depends_on: depends_on: {}
db:
condition: service_healthy
backend: backend:
<<: *backend_defaults <<: *backend_defaults
@@ -30,27 +28,6 @@ services:
- sites:/home/frappe/frappe-bench/sites - sites:/home/frappe/frappe-bench/sites
- assets:/home/frappe/frappe-bench/sites/assets:ro - assets:/home/frappe/frappe-bench/sites/assets:ro
db:
image: mariadb:10.6
healthcheck:
test: mysqladmin ping -h localhost --password=${DB_PASSWORD}
interval: 1s
retries: 15
command:
- --character-set-server=utf8mb4
- --collation-server=utf8mb4_unicode_ci
- --skip-character-set-client-handshake
- --skip-innodb-read-only-compressed # Temporary fix for MariaDB 10.6
environment:
MYSQL_ROOT_PASSWORD: ${DB_PASSWORD:?No db password set}
volumes:
- db-data:/var/lib/mysql
redis:
image: redis:6.2-alpine
volumes:
- redis-data:/data
frontend: frontend:
image: frappe/frappe-nginx:${FRAPPE_VERSION} image: frappe/frappe-nginx:${FRAPPE_VERSION}
environment: environment:
@@ -69,18 +46,6 @@ services:
- traefik.http.routers.frontend-http.entrypoints=web - traefik.http.routers.frontend-http.entrypoints=web
- traefik.http.routers.frontend-http.rule=HostRegexp(`{any:.+}`) - traefik.http.routers.frontend-http.rule=HostRegexp(`{any:.+}`)
proxy:
image: traefik:2.5
command:
- --providers.docker
- --providers.docker.exposedbydefault=false
- --entrypoints.web.address=:80
ports:
- 80:80
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
userns_mode: host
websocket: websocket:
<<: *depends_on_configurator <<: *depends_on_configurator
image: frappe/frappe-socketio:${FRAPPE_VERSION} image: frappe/frappe-socketio:${FRAPPE_VERSION}
@@ -107,5 +72,3 @@ services:
volumes: volumes:
sites: sites:
assets: assets:
db-data:
redis-data:

323
docs/docker-swarm.md
View File

@@ -1,295 +1,50 @@
### Prerequisites ## Prerequisites
IMPORTANT: All commands are executed on live server with public IP and DNS Configured. - [yq](https://mikefarah.gitbook.io/yq)
- [docker-compose](https://docs.docker.com/compose/)
- [docker swarm](https://docs.docker.com/engine/swarm/)
#### Setup docker swarm #### Generate setup for docker swarm
Follow [dockerswarm.rocks](https://dockerswarm.rocks) guide to setup Docker swarm, Traefik and Portainer. Generate the swarm compatible YAML,
Use Portainer for rest of the guide ```bash
docker-compose -f compose.yaml \
### Create Config -f overrides/compose.erpnext.yaml \
-f overrides/compose.swarm.yaml \
Configs > Add Config > `frappe-mariadb-config` -f overrides/compose.https.yaml \
config \
``` | yq eval 'del(.services.*.depends_on) | del(.services.frontend.labels)' - \
[mysqld] | yq eval '.services.proxy.command += "--providers.docker.swarmmode"' - > \
character-set-client-handshake = FALSE ~/gitops/compose.yaml
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
[mysql]
default-character-set = utf8mb4
``` ```
### Create Secret In case you need to generate config for multiple benches. Install the proxy separately only once and generate stacks for each bench as follows:
Secret > Add Secret > `frappe-mariadb-root-password` ```bash
# Setup Bench $BENCH_SUFFIX
``` export BENCH_SUFFIX=one
longsecretpassword docker-compose -f compose.yaml \
-f overrides/compose.erpnext.yaml \
-f overrides/compose.swarm.yaml \
config \
| yq eval 'del(.services.*.depends_on) | del(.services.frontend.labels)' - \
| sed "s|frontend|frontend-${BENCH_SUFFIX}|g" \
| yq eval ".services.frontend-${BENCH_SUFFIX}.\"networks\"=[\"traefik-public\",\"default\"]" - \
| yq eval ".\"networks\"={\"traefik-public\":{\"external\":true}}" - > \
~/gitops/compose-${BENCH_SUFFIX}.yaml
``` ```
Note down this password. Commands explained:
It is only available in mariadb containers at location `/run/secrets/frappe-mariadb-root-password` later
### Deploy MariaDB Replication - `docker-compose -f ... -f ... config`, this command generates the YAML based on the overrides
- `yq eval 'del(.services.*.depends_on) | del(.services.frontend.labels)'`, this command removes the `depends_on` from all services and `labels` from frontend generated from previous command.
- `yq eval '.services.proxy.command += "--providers.docker.swarmmode"'`, this command enables swarmmode for traefik proxy.
- `sed "s|frontend|frontend-${BENCH_SUFFIX}|g"`, this command replaces the service name `frontend` with `frontend-` and `BENCH_SUFFIX` provided.
- `yq eval ".services.frontend-${BENCH_SUFFIX}.\"networks\"=[\"traefik-public\",\"default\"]"`, this command attaches `traefik-public` and `default` network to frontend service.
- `yq eval ".\"networks\"={\"traefik-public\":{\"external\":true}}"`, this commands adds external network `traefik-public` to the stack
Stacks > Add Stacks > `frappe-mariadb` Notes:
- Set `BENCH_SUFFIX` to the stack name. the stack will be located at `~/gitops/compose-${BENCH_SUFFIX}.yaml`.
```yaml - `traefik-public` is assumed to be the network for traefik loadbalancer for swarm.
version: "3.7" - Once the stack YAML is generated, you can edit it further for advance setup and commit it to your gitops
services:
mariadb-master:
image: "bitnami/mariadb:10.3"
deploy:
restart_policy:
condition: on-failure
configs:
- source: frappe-mariadb-config
target: /opt/bitnami/mariadb/conf/bitnami/my_custom.cnf
networks:
- frappe-network
secrets:
- frappe-mariadb-root-password
volumes:
- "mariadb_master_data:/bitnami/mariadb"
environment:
- MARIADB_REPLICATION_MODE=master
- MARIADB_REPLICATION_USER=repl_user
- MARIADB_REPLICATION_PASSWORD_FILE=/run/secrets/frappe-mariadb-root-password
- MARIADB_ROOT_PASSWORD_FILE=/run/secrets/frappe-mariadb-root-password
mariadb-slave:
image: "bitnami/mariadb:10.3"
deploy:
restart_policy:
condition: on-failure
configs:
- source: frappe-mariadb-config
target: /opt/bitnami/mariadb/conf/bitnami/my_custom.cnf
networks:
- frappe-network
secrets:
- frappe-mariadb-root-password
volumes:
- "mariadb_slave_data:/bitnami/mariadb"
environment:
- MARIADB_REPLICATION_MODE=slave
- MARIADB_REPLICATION_USER=repl_user
- MARIADB_REPLICATION_PASSWORD_FILE=/run/secrets/frappe-mariadb-root-password
- MARIADB_MASTER_HOST=mariadb-master
- MARIADB_MASTER_PORT_NUMBER=3306
- MARIADB_MASTER_ROOT_PASSWORD_FILE=/run/secrets/frappe-mariadb-root-password
volumes:
mariadb_master_data:
mariadb_slave_data:
configs:
frappe-mariadb-config:
external: true
secrets:
frappe-mariadb-root-password:
external: true
networks:
frappe-network:
name: frappe-network
attachable: true
```
### Deploy Frappe/ERPNext
Stacks > Add Stacks > `frappe-bench-v13`
```yaml
version: "3.7"
services:
redis-cache:
image: redis:latest
volumes:
- redis-cache-vol:/data
deploy:
restart_policy:
condition: on-failure
networks:
- frappe-network
redis-queue:
image: redis:latest
volumes:
- redis-queue-vol:/data
deploy:
restart_policy:
condition: on-failure
networks:
- frappe-network
redis-socketio:
image: redis:latest
volumes:
- redis-socketio-vol:/data
deploy:
restart_policy:
condition: on-failure
networks:
- frappe-network
erpnext-nginx:
image: frappe/erpnext-nginx:${ERPNEXT_VERSION?Variable ERPNEXT_VERSION not set}
environment:
- UPSTREAM_REAL_IP_ADDRESS=10.0.0.0/8
- FRAPPE_PY=erpnext-python
- FRAPPE_PY_PORT=8000
- FRAPPE_SOCKETIO=frappe-socketio
- SOCKETIO_PORT=9000
volumes:
- sites-vol:/var/www/html/sites:rw
- assets-vol:/assets:rw
networks:
- frappe-network
- traefik-public
deploy:
restart_policy:
condition: on-failure
labels:
- "traefik.docker.network=traefik-public"
- "traefik.enable=true"
- "traefik.constraint-label=traefik-public"
- "traefik.http.routers.erpnext-nginx.rule=Host(${SITES?Variable SITES not set})"
- "traefik.http.routers.erpnext-nginx.entrypoints=http"
- "traefik.http.routers.erpnext-nginx.middlewares=https-redirect"
- "traefik.http.routers.erpnext-nginx-https.rule=Host(${SITES?Variable SITES not set})"
- "traefik.http.routers.erpnext-nginx-https.entrypoints=https"
- "traefik.http.routers.erpnext-nginx-https.tls=true"
- "traefik.http.routers.erpnext-nginx-https.tls.certresolver=le"
- "traefik.http.services.erpnext-nginx.loadbalancer.server.port=8080"
erpnext-python:
image: frappe/erpnext-worker:${ERPNEXT_VERSION?Variable ERPNEXT_VERSION not set}
deploy:
restart_policy:
condition: on-failure
environment:
- MARIADB_HOST=${MARIADB_HOST?Variable MARIADB_HOST not set}
- REDIS_CACHE=redis-cache:6379
- REDIS_QUEUE=redis-queue:6379
- REDIS_SOCKETIO=redis-socketio:6379
- SOCKETIO_PORT=9000
- AUTO_MIGRATE=1
volumes:
- sites-vol:/home/frappe/frappe-bench/sites:rw
- assets-vol:/home/frappe/frappe-bench/sites/assets:rw
networks:
- frappe-network
frappe-socketio:
image: frappe/frappe-socketio:${FRAPPE_VERSION?Variable FRAPPE_VERSION not set}
deploy:
restart_policy:
condition: on-failure
volumes:
- sites-vol:/home/frappe/frappe-bench/sites:rw
networks:
- frappe-network
erpnext-worker-default:
image: frappe/erpnext-worker:${ERPNEXT_VERSION?Variable ERPNEXT_VERSION not set}
deploy:
restart_policy:
condition: on-failure
command: worker
volumes:
- sites-vol:/home/frappe/frappe-bench/sites:rw
networks:
- frappe-network
erpnext-worker-short:
image: frappe/erpnext-worker:${ERPNEXT_VERSION?Variable ERPNEXT_VERSION not set}
deploy:
restart_policy:
condition: on-failure
command: worker
environment:
- WORKER_TYPE=short
volumes:
- sites-vol:/home/frappe/frappe-bench/sites:rw
networks:
- frappe-network
erpnext-worker-long:
image: frappe/erpnext-worker:${ERPNEXT_VERSION?Variable ERPNEXT_VERSION not set}
deploy:
restart_policy:
condition: on-failure
command: worker
environment:
- WORKER_TYPE=long
volumes:
- sites-vol:/home/frappe/frappe-bench/sites:rw
networks:
- frappe-network
frappe-schedule:
image: frappe/erpnext-worker:${ERPNEXT_VERSION?Variable ERPNEXT_VERSION not set}
deploy:
restart_policy:
condition: on-failure
command: schedule
volumes:
- sites-vol:/home/frappe/frappe-bench/sites:rw
networks:
- frappe-network
volumes:
redis-cache-vol:
redis-queue-vol:
redis-socketio-vol:
assets-vol:
sites-vol:
networks:
traefik-public:
external: true
frappe-network:
external: true
```
Use environment variables:
- `ERPNEXT_VERSION` variable to be set to desired version of ERPNext. e.g. 12.10.0
- `FRAPPE_VERSION` variable to be set to desired version of Frappe Framework. e.g. 12.7.0
- `MARIADB_HOST=frappe-mariadb_mariadb-master`
- `SITES` variable is list of sites in back tick and separated by comma
```
SITES=`site1.example.com`,`site2.example.com`
```
### Create new site job
1. Containers > Add Container > `add-site1-example-com`
2. Select Image frappe/erpnext-worker:v13
3. Set command as `new`
4. Select network `frappe-network`
5. Select Volume `frappe-bench-v13_sites-vol` and mount in container `/home/frappe/frappe-bench/sites`
6. Env variables:
- MYSQL_ROOT_PASSWORD=longsecretpassword
- SITE_NAME=site1.example.com
- INSTALL_APPS=erpnext
7. Start container
### Migrate Sites job
1. Containers > Add Container > `migrate-sites`
2. Select Image frappe/erpnext-worker:v13
3. Set command as `migrate`
4. Select network `frappe-network`
5. Select Volume `frappe-bench-v13_sites-vol` and mount in container `/home/frappe/frappe-bench/sites`
6. Env variables:
- MAINTENANCE_MODE=1
7. Start container

35
docs/images-and-compose-files.md
View File

@@ -9,7 +9,7 @@ There's 4 images that you can find in `/build` directory:
> `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. > `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. > 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 our builds more efficient.
# Compose files # Compose files
@@ -23,8 +23,8 @@ 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. - `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/). - `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`. - `db`. Optional service that runs [MariaDB](https://mariadb.com) if you also use `overrides/compose.mariadb.yaml` or [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. - `redis`. Optional service that runs [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. - `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`). - `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). - `websocket`. Node server that runs [Socket.IO](https://socket.io).
@@ -35,15 +35,20 @@ All services are described in `compose.yaml`
We have several [overrides](https://docs.docker.com/compose/extends/): We have several [overrides](https://docs.docker.com/compose/extends/):
- `overrides/compose.proxy.yaml`. Adds traefik proxy to setup.
- `overrides/compose.noproxy.yaml`. Publishes `frontend` ports directly without any proxy.
- `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.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.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. - `overrides/compose.mariadb.yaml`. Adds `db` service and sets its image to MariaDB.
- `overrides/compose.postgres.yaml`. Adds `db` service and sets its image to Postgres. Note that ERPNext currently doesn't support Postgres.
- `overrides/compose.redis.yaml`. Adds `redis` service and sets its image to `redis`.
- `overrides/compose.swarm.yaml`. Workaround override for generating swarm stack.
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: 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 ```bash
# Point to main compose file (compose.yaml) and add one more. # Point to main compose file (compose.yaml) and add one more.
docker-compose -f compose.yaml -f overrides/compose.erpnext.yaml docker-compose -f compose.yaml -f overrides/compose.erpnext.yaml config
``` ```
That's it! Of course, we also have to setup `.env` before all of that, but that's not the point. That's it! Of course, we also have to setup `.env` before all of that, but that's not the point.
@@ -60,6 +65,26 @@ Frappe framework release. You can find all releases [here](https://github.com/fr
Password for MariaDB (or Postgres) database. Password for MariaDB (or Postgres) database.
### `DB_HOST`
Hostname for MariaDB (or Postgres) database. Set only if external service for database is used.
### `DB_PORT`
Port for MariaDB (3306) or Postgres (5432) database. Set only if external service for database is used.
### `REDIS_CACHE`
Hostname for redis server to store cache. Set only if external service for redis is used.
### `REDIS_QUEUE`
Hostname for redis server to store queue data. Set only if external service for redis is used.
### `REDIS_SOCKETIO`
Hostname for redis server to store socketio data. Set only if external service for redis is used.
### `ERPNEXT_VERSION` ### `ERPNEXT_VERSION`
ERPNext [release](https://github.com/frappe/frappe/releases). This variable is required if you use ERPNext override. ERPNext [release](https://github.com/frappe/frappe/releases). This variable is required if you use ERPNext override.

197
docs/multi-bench.md
View File

@@ -1,197 +0,0 @@
# Multi bench
This setup separates all services such that only required ones can be deployed.
This is suitable when multiple services are installed on cluster with shared proxy/router, database, cache etc.
Make sure you've cloned this repository and switch to the directory before executing following commands.
## Setup Environment Variables
Copy the example docker environment file to `.env`:
```sh
cp env-example .env
```
To get started, copy the existing `env-example` file to `.env`. By default, the file will contain the following variables:
- `VERSION=edge`
- In this case, `edge` corresponds to `develop`. To setup any other version, you may use the branch name or version specific tags. (eg. v13.0.0, version-12, v11.1.15, v11)
- `MYSQL_ROOT_PASSWORD=admin`
- Bootstraps a MariaDB container with this value set as the root password. If a managed MariaDB instance is used, there is no need to set the password here.
- `MARIADB_HOST=mariadb`
- Sets the hostname to `mariadb`. This is required if the database is managed by the containerized MariaDB instance.
- In case of a separately managed database setups, set the value to the database's hostname/IP/domain.
- `SITES=site1.domain.com,site2.domain.com`
- List of sites that are part of the deployment "bench" Each site is separated by a comma(,).
- If LetsEncrypt is being setup, make sure that the DNS for all the site's domains correctly point to the current instance.
- `LETSENCRYPT_EMAIL=your.email@your.domain.com`
- Email for LetsEncrypt expiry notification. This is only required if you are setting up LetsEncrypt.
Notes:
- docker-compose-erpnext.yml and docker-compose-frappe.yml set `AUTO_MIGRATE` environment variable to `1`.
- `AUTO_MIGRATE` checks if there is semver bump or git hash change in case of develop branch and automatically migrates the sites on container start up.
- It is good practice to use image tag for specific version instead of latest. e.g `frappe-socketio:v12.5.1`, `erpnext-nginx:v12.7.1`.
## Local deployment for testing
For trying out locally or to develop apps using ERPNext REST API port 80 must be published.
Following command will start the needed containers and expose ports.
For Erpnext:
```sh
docker-compose \
--project-name <project-name> \
-f installation/docker-compose-common.yml \
-f installation/docker-compose-erpnext.yml \
-f installation/erpnext-publish.yml \
up -d
```
For Frappe:
```sh
docker-compose \
--project-name <project-name> \
-f installation/docker-compose-common.yml \
-f installation/docker-compose-frappe.yml \
-f installation/frappe-publish.yml \
up -d
```
Make sure to replace `<project-name>` with the desired name you wish to set for the project.
Notes:
- New site (first site) needs to be added after starting the services.
- The local deployment is for testing and REST API development purpose only
- A complete development environment is available [here](../development)
- The site names are limited to patterns matching \*.localhost by default
- Additional site name patterns can be added by editing /etc/hosts of your host machine
## Deployment for production
### Setup Letsencrypt Nginx Proxy Companion
Letsencrypt Nginx Proxy Companion can optionally be setup to provide SSL. This is recommended for instances accessed over the internet.
Your DNS will need to be configured correctly for Letsencrypt to verify your domain.
To setup the proxy companion, run the following commands:
```sh
cd $HOME
git clone https://github.com/evertramos/docker-compose-letsencrypt-nginx-proxy-companion.git
cd docker-compose-letsencrypt-nginx-proxy-companion
cp .env.sample .env
./start.sh
```
It will create the required network and configure containers for Letencrypt ACME.
For more details, see the [Letsencrypt Nginx Proxy Companion github repo](https://github.com/evertramos/docker-compose-letsencrypt-nginx-proxy-companion). Letsencrypt Nginx Proxy Companion github repo works by automatically proxying to containers with the `VIRTUAL_HOST` environmental variable.
Notes:
- `SITES` variables from `env-example` is set as `VIRTUAL_HOST`
- `LETSENCRYPT_EMAIL` variables from `env-example` is used as it is.
- This is simple nginx + letsencrypt solution. Any other solution can be setup. Above two variables can be re-used or removed in case any other reverse-proxy is used.
### Start Frappe/ERPNext Services
To start the Frappe/ERPNext services for production, run the following command:
```sh
docker-compose \
--project-name <project-name> \
-f installation/docker-compose-common.yml \
-f installation/docker-compose-erpnext.yml \
-f installation/docker-compose-networks.yml \
up -d
```
Make sure to replace `<project-name>` with any desired name you wish to set for the project.
Notes:
- Use `docker-compose-frappe.yml` in case you need only Frappe without ERPNext.
- New site (first site) needs to be added after starting the services.
## Docker containers
This repository contains the following docker-compose files, each one containing the described images:
- docker-compose-common.yml
- redis-cache
- volume: redis-cache-vol
- redis-queue
- volume: redis-queue-vol
- redis-socketio
- volume: redis-socketio-vol
- mariadb: main database
- volume: mariadb-vol
- docker-compose-erpnext.yml
- erpnext-nginx: serves static assets and proxies web request to the appropriate container, allowing to offer all services on the same port.
- volume: assets-vol
- erpnext-python: main application code
- frappe-socketio: enables realtime communication to the user interface through websockets
- frappe-worker-default: background runner
- frappe-worker-short: background runner for short-running jobs
- frappe-worker-long: background runner for long-running jobs
- frappe-schedule
- docker-compose-frappe.yml
- frappe-nginx: serves static assets and proxies web request to the appropriate container, allowing to offer all services on the same port.
- volume: assets-vol, sites-vol
- erpnext-python: main application code
- volume: sites-vol
- frappe-socketio: enables realtime communication to the user interface through websockets
- volume: sites-vol
- frappe-worker-default: background runner
- volume: sites-vol
- frappe-worker-short: background runner for short-running jobs
- volume: sites-vol
- frappe-worker-long: background runner for long-running jobs
- volume: sites-vol
- frappe-schedule
- volume: sites-vol
- docker-compose-networks.yml: this yaml define the network to communicate with _Letsencrypt Nginx Proxy Companion_.
- erpnext-publish.yml: this yml extends erpnext-nginx service to publish port 80, can only be used with docker-compose-erpnext.yml
- frappe-publish.yml: this yml extends frappe-nginx service to publish port 80, can only be used with docker-compose-frappe.yml
## Updating and Migrating Sites
Switch to the root of the `frappe_docker` directory before running the following commands:
```sh
# Update environment variable VERSION
nano .env
# Pull new images
docker-compose \
-f installation/docker-compose-common.yml \
-f installation/docker-compose-erpnext.yml \
pull
# Restart containers
docker-compose \
--project-name <project-name> \
-f installation/docker-compose-common.yml \
-f installation/docker-compose-erpnext.yml \
-f installation/docker-compose-networks.yml \
up -d
docker run \
-e "MAINTENANCE_MODE=1" \
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
--network <project-name>_default \
frappe/erpnext-worker:$VERSION migrate
```

95
docs/setup-options.md Normal file
View File

@@ -0,0 +1,95 @@
# Containerized Production Setup
Make sure you've cloned this repository and switch to the directory before executing following commands.
Commands will generate YAML as per the environment for setup.
## Setup Environment Variables
Copy the example docker environment file to `.env`:
```sh
cp example.env .env
```
Note: To know more about environment variable [read here](./images-and-compose-files#configuration). Set the necessary variables in the `.env` file.
## Generate docker-compose.yml for variety of setups
### Setup Frappe without proxy and external MariaDB and Redis
```sh
# Generate YAML
docker-compose -f compose.yaml -f overrides/compose.noproxy.yaml config > ~/gitops/docker-compose.yml
# Start containers
docker-compose --project <project-name> -f ~/gitops/docker-compose.yml up -d
```
### Setup ERPNext with proxy and external MariaDB and Redis
```sh
# Generate YAML
docker-compose -f compose.yaml \
-f overrides/compose.proxy.yaml \
-f overrides/compose.erpnext.yaml \
config > ~/gitops/docker-compose.yml
# Start containers
docker-compose --project <project-name> -f ~/gitops/docker-compose.yml up -d
```
### Setup Frappe using containerized MariaDB and Redis with Letsencrypt certificates.
```sh
# Generate YAML
docker-compose -f compose.yaml \
-f overrides/compose.mariadb.yaml \
-f overrides/compose.redis.yaml \
-f overrides/compose.https.yaml \
config > ~/gitops/docker-compose.yml
# Start containers
docker-compose --project <project-name> -f ~/gitops/docker-compose.yml up -d
```
### Setup ERPNext using containerized MariaDB and Redis with Letsencrypt certificates.
```sh
# Generate YAML
docker-compose -f compose.yaml \
-f overrides/compose.erpnext.yaml \
-f overrides/compose.mariadb.yaml \
-f overrides/compose.redis.yaml \
-f overrides/compose.https.yaml \
config > ~/gitops/docker-compose.yml
# Start containers
docker-compose --project <project-name> -f ~/gitops/docker-compose.yml up -d
```
Notes:
- Make sure to replace `<project-name>` with the desired name you wish to set for the project.
- This setup is not to be used for development. A complete development environment is available [here](../development)
## Updating Images
Switch to the root of the `frappe_docker` directory before running the following commands:
```sh
# Update environment variables ERPNEXT_VERSION and FRAPPE_VERSION
nano .env
# Pull new images
docker-compose -f compose.yaml \
-f overrides/erpnext.yaml \
# ... your other overrides
config > ~/gitops/docker-compose.yml
docker-compose --project <project-name> -f ~/gitops/docker-compose.yml pull
# Restart containers
docker-compose --project <project-name> -f ~/gitops/docker-compose.yml up -d
```
To migrate sites refer [site operations](./site-operations.md#migrate-site)

129
docs/single-bench.md
View File

@@ -1,129 +0,0 @@
# Single Bench
This setup starts traefik service as part of single docker-compose project. It is quick to get started locally or on production for a single server with single deployment.
This is not suitable when multiple services are installed on cluster with shared proxy/router, database, cache etc.
Make sure you've cloned this repository and switch to the directory before executing following commands.
## Setup Environment Variables
Copy the example docker environment file to `.env`:
For local setup
```sh
cp env-local .env
```
For production
```sh
cp env-production .env
```
To get started, copy the existing `env-local` or `env-production` file to `.env`. By default, the file will contain the following variables:
- `ERPNEXT_VERSION=edge`
- In this case, `edge` corresponds to `develop`. To setup any other version, you may use the branch name or version specific tags. (eg. v13.0.0, version-12, v11.1.15, v11).
- `FRAPPE_VERSION=edge`
- In this case, `edge` corresponds to `develop`. To setup any other version, you may use the branch name or version specific tags. (eg. v13.0.0, version-12, v11.1.15, v11).
- `MARIADB_HOST=mariadb`
- Sets the hostname to `mariadb`. This is required if the database is managed by the containerized MariaDB instance.
- `MYSQL_ROOT_PASSWORD=admin`
- Bootstraps a MariaDB container with this value set as the root password. If a managed MariaDB instance is used, there is no need to set the password here.
- In case of a separately managed database setups, set the value to the database's hostname/IP/domain.
- `SITE_NAME=erp.example.com`
- Creates this site after starting all services and installs ERPNext. Site name must be resolvable by users machines and the ERPNext components. e.g. `erp.example.com` or `mysite.localhost`.
- `` SITES=`erp.example.com` ``
- List of sites that are part of the deployment "bench" Each site is separated by a comma(,) and quoted in backtick (`). By default site created by `SITE_NAME` variable is added here.
- If LetsEncrypt is being setup, make sure that the DNS for all the site's domains correctly point to the current instance.
- `DB_ROOT_USER=root`
- MariaDB root username
- `ADMIN_PASSWORD=admin`
- Password for the `Administrator` user, credentials after install `Administrator:$ADMIN_PASSWORD`.
- `INSTALL_APPS=erpnext`
- Apps to install, the app must be already in the container image, to install other application read the [instructions on installing custom apps](../custom_app/README.md).
- `LETSENCRYPT_EMAIL=email@example.com`
- Email for LetsEncrypt expiry notification. This is only required if you are setting up LetsEncrypt.
- `ENTRYPOINT_LABEL=traefik.http.routers.erpnext-nginx.entrypoints=websecure`
- Related to the traefik configuration, says all traffic from outside should come from HTTP or HTTPS, for local development should be web, for production websecure. if redirection is needed, read below.
- `CERT_RESOLVER_LABEL=traefik.http.routers.erpnext-nginx.tls.certresolver=myresolver`
- Which traefik resolver to use to get TLS certificate, sets `erpnext.local.no-cert-resolver` for local setup.
- `` HTTPS_REDIRECT_RULE_LABEL=traefik.http.routers.http-catchall.rule=hostregexp(`{host:.+}`) ``
- Related to the traefik https redirection configuration, sets `erpnext.local.no-redirect-rule` for local setup.
- `HTTPS_REDIRECT_ENTRYPOINT_LABEL=traefik.http.routers.http-catchall.entrypoints=web`
- Related to the traefik https redirection configuration, sets `erpnext.local.no-entrypoint` for local setup.
- `HTTPS_REDIRECT_MIDDLEWARE_LABEL=traefik.http.routers.http-catchall.middlewares=redirect-to-https`
- Related to the traefik https redirection configuration, sets `erpnext.local.no-middleware` for local setup.
- `HTTPS_USE_REDIRECT_MIDDLEWARE_LABEL=traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https`
- Related to the traefik https redirection configuration, sets `erpnext.local-no-redirect-middleware` for local setup.
Notes:
- `AUTO_MIGRATE` variable is set to `1` by default. It checks if there is semver bump or git hash change in case of develop branch and automatically migrates the sites on container start up.
- It is good practice to use image tag for specific version instead of latest. e.g `frappe-socketio:v12.5.1`, `erpnext-nginx:v12.7.1`.
## Start containers
Execute the following command:
```sh
docker-compose --project-name <project-name> up -d
```
Make sure to replace `<project-name>` with the desired name you wish to set for the project.
Notes:
- If it is the first time running and site is being initialized, _it can take multiple minutes for the site to be up_. Monitor `site-creator` container logs to check progress. Use command `docker logs <project-name>_site-creator_1 -f`
- After the site is ready the username is `Administrator` and the password is `$ADMIN_PASSWORD`
- The local deployment is for testing and REST API development purpose only
- A complete development environment is available [here](../development)
## Docker containers
The docker-compose file contains following services:
- traefik: manages letsencrypt
- volume: cert-vol
- redis-cache: cache store
- volume: redis-cache-vol
- redis-queue: used by workers
- volume: redis-queue-vol
- redis-socketio: used by socketio service
- volume: redis-socketio-vol
- mariadb: main database
- volume: mariadb-vol
- erpnext-nginx: serves static assets and proxies web request to the appropriate container, allowing to offer all services on the same port.
- volume: assets-vol and sites-vol
- erpnext-python: main application code
- volume: sites-vol and sites-vol
- frappe-socketio: enables realtime communication to the user interface through websockets
- volume: sites-vol
- erpnext-worker-default: background runner
- volume: sites-vol
- erpnext-worker-short: background runner for short-running jobs
- volume: sites-vol
- erpnext-worker-long: background runner for long-running jobs
- volume: sites-vol
- erpnext-schedule
- volume: sites-vol
- site-creator: run once container to create new site.
- volume: sites-vol
## Updating and Migrating Sites
Switch to the root of the `frappe_docker` directory before running the following commands:
```sh
# Update environment variables ERPNEXT_VERSION and FRAPPE_VERSION
nano .env
# Pull new images
docker-compose pull
# Restart containers
docker-compose --project-name <project-name> up -d
```

10
docs/site-operations.md
View File

@@ -71,3 +71,13 @@ For reference of commands like `backup`, `drop-site` or `migrate` check [officia
```sh ```sh
docker-compose exec backend bench --help docker-compose exec backend bench --help
``` ```
## Migrate site
Note:
- Wait for the `db` service to start and `configurator` to exit before trying to migrate a site. Usually this takes up to 10 seconds.
```sh
docker-compose exec backend bench --site <site-name> migrate
```

5
example.env
View File

@@ -2,6 +2,11 @@
FRAPPE_VERSION=v13.17.0 FRAPPE_VERSION=v13.17.0
DB_PASSWORD=123 DB_PASSWORD=123
DB_HOST=
DB_PORT=
REDIS_CACHE=
REDIS_QUEUE=
REDIS_SOCKETIO=
# Only with ERPNext override # Only with ERPNext override
ERPNEXT_VERSION=v13.17.0 ERPNEXT_VERSION=v13.17.0

2
overrides/compose.https.yaml
View File

@@ -7,6 +7,7 @@ services:
- traefik.http.routers.frontend-http.tls.certresolver=main-resolver - traefik.http.routers.frontend-http.tls.certresolver=main-resolver
proxy: proxy:
image: traefik:2.5
command: command:
- --providers.docker=true - --providers.docker=true
- --providers.docker.exposedbydefault=false - --providers.docker.exposedbydefault=false
@@ -19,6 +20,7 @@ services:
- --certificatesResolvers.main-resolver.acme.email=${LETSENCRYPT_EMAIL:?No Let's Encrypt email set} - --certificatesResolvers.main-resolver.acme.email=${LETSENCRYPT_EMAIL:?No Let's Encrypt email set}
- --certificatesResolvers.main-resolver.acme.storage=/letsencrypt/acme.json - --certificatesResolvers.main-resolver.acme.storage=/letsencrypt/acme.json
ports: ports:
- 80:80
- 443:443 - 443:443
volumes: volumes:
- cert-data:/letsencrypt - cert-data:/letsencrypt

27
overrides/compose.mariadb.yaml Normal file
View File

@@ -0,0 +1,27 @@
services:
configurator:
environment:
DB_HOST: db
DB_PORT: 3306
depends_on:
db:
condition: service_healthy
db:
image: mariadb:10.6
healthcheck:
test: mysqladmin ping -h localhost --password=${DB_PASSWORD}
interval: 1s
retries: 15
command:
- --character-set-server=utf8mb4
- --collation-server=utf8mb4_unicode_ci
- --skip-character-set-client-handshake
- --skip-innodb-read-only-compressed # Temporary fix for MariaDB 10.6
environment:
MYSQL_ROOT_PASSWORD: ${DB_PASSWORD:?No db password set}
volumes:
- db-data:/var/lib/mysql
volumes:
db-data:

5
overrides/compose.noproxy.yaml Normal file
View File

@@ -0,0 +1,5 @@
services:
frontend:
ports:
- 8080:8080
- 80:80 # For old images

7
overrides/compose.postgres.yaml
View File

@@ -1,9 +1,11 @@
services: services:
configurator: configurator:
environment: environment:
DB_HOST: db
DB_PORT: 5432 DB_PORT: 5432
depends_on: depends_on:
- db db:
condition: service_healthy
db: db:
image: postgres:14.1 image: postgres:14.1
@@ -16,3 +18,6 @@ services:
POSTGRES_PASSWORD: ${DB_PASSWORD:?No db password set} POSTGRES_PASSWORD: ${DB_PASSWORD:?No db password set}
volumes: volumes:
- db-data:/var/lib/postgresql - db-data:/var/lib/postgresql
volumes:
db-data:

12
overrides/compose.proxy.yaml Normal file
View File

@@ -0,0 +1,12 @@
services:
proxy:
image: traefik:2.5
command:
- --providers.docker
- --providers.docker.exposedbydefault=false
- --entrypoints.web.address=:80
ports:
- 80:80
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
userns_mode: host

17
overrides/compose.redis.yaml Normal file
View File

@@ -0,0 +1,17 @@
services:
configurator:
environment:
REDIS_CACHE: redis:6379/0
REDIS_QUEUE: redis:6379/1
REDIS_SOCKETIO: redis:6379/2
depends_on:
redis:
condition: service_healthy
redis:
image: redis:6.2-alpine
volumes:
- redis-data:/data
volumes:
redis-data:

10
overrides/compose.swarm.yaml Normal file
View File

@@ -0,0 +1,10 @@
services:
frontend:
deploy:
restart_policy:
condition: on-failure
labels:
traefik.enable: true
traefik.http.services.frontend.loadbalancer.server.port: 8080
traefik.http.routers.frontend-http.entrypoints: websecure
traefik.http.routers.frontend-http.tls.certresolver: main-resolver