From 468c114dd72b94c872a8692a3c9ad27cccfb89bd Mon Sep 17 00:00:00 2001 From: Revant Nandgaonkar Date: Sat, 19 Mar 2022 15:16:39 +0530 Subject: [PATCH] docs: single server setup example --- README.md | 5 +- docs/single-server-example.md | 248 ++++++++++++++++++++++++++ overrides/compose.mariadb-shared.yaml | 26 +++ overrides/compose.multi-bench.yaml | 41 +++++ overrides/compose.traefik-docker.yaml | 69 +++++++ 5 files changed, 387 insertions(+), 2 deletions(-) create mode 100644 docs/single-server-example.md create mode 100644 overrides/compose.mariadb-shared.yaml create mode 100644 overrides/compose.multi-bench.yaml create mode 100644 overrides/compose.traefik-docker.yaml diff --git a/README.md b/README.md index af05681c..351c8edb 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,9 @@ We provide simple and intuitive production setup with prebuilt Frappe and ERPNex Also, there's docs to help with deployment: -- [setup options](docs/setup-options.md), -- in cluster: +- [Setup options](docs/setup-options.md) +- Examples: + - [Single Server](docs/single-server-example.md) - [Docker Swarm](docs/docker-swarm.md), - [Kubernetes (frappe/helm)](https://helm.erpnext.com), - [site operations](docs/site-operations.md). diff --git a/docs/single-server-example.md b/docs/single-server-example.md new file mode 100644 index 00000000..d2c2e029 --- /dev/null +++ b/docs/single-server-example.md @@ -0,0 +1,248 @@ +### Single Server Example + +In this use case we have a single server with a static IP attached to it. It can be used in scenarios where one powerful VM has multiple benches and applications or one entry level VM with single site. For single bench, single site setup follow only up to the point where first bench and first site is added. If you choose this setup you can only scale vertically. If you need to scale horizontally you'll need to backup the sites and restore them on to cluster setup. + +We will setup the following: + +- Install docker and docker compose v2 on linux server. +- Install traefik service for internal load balancer and letsencrypt. +- Install MariaDB with containers. +- Setup project called `erpnext-one` and create sites `one.example.com` and `two.example.com` in the project. +- Setup project called `erpnext-two` and create sites `three.example.com` and `four.example.com` in the project. + +Explanation: + +Single instance of **Traefik** will be installed and act as internal loadbalancer for multiple benches and sites hosted on the server. It can also load balance other applications along with frappe benches, e.g. wordpress, metabase, etc. We only expose the ports `80` and `443` once with this instance of traefik. Traefik will also take care of letsencrypt automation for all sites installed on the server. *Why choose Traefik over Nginx Proxy Manager?* Traefik doesn't need additional DB service and can store certificates in a json file in a volume. Traefik will also be used in swarm setup keeping things consistent for understanding. + +Single instance of **MariaDB** will be installed and act as database service for all the benches/projects installed on the server. + +Each instance of ERPNext project (bench) will have its own redis, socketio, gunicorn, nginx, workers and scheduler. It will connect to internal MariaDB by connecting to MariaDB network. It will expose sites to public through Traefik by connecting to Traefik network. + +### Install Docker + +Easiest way to install docker is to use the [convenience script](https://docs.docker.com/engine/install/ubuntu/#install-using-the-convenience-script). + +```shell +curl -fsSL https://get.docker.com | bash +``` + +Note: The documentation assumes Ubuntu LTS server is used. Use any distribution as long as the docker convenience script works. If the convenience script doesn't work, you'll need to install docker manually. + +### Install Compose V2 + +Refer [original documentation](https://docs.docker.com/compose/cli-command/#install-on-linux) for updated version. + +```shell +DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker} +mkdir -p $DOCKER_CONFIG/cli-plugins +curl -SL https://github.com/docker/compose/releases/download/v2.2.3/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose +chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose +``` + +### Create directory to store your configuration files. + +```shell +mkdir -p ~/gitops/overrides +``` + +This directory will store all the resources that we use for setup. We will also keep the environment files in this directory as there will be multiple projects with different environment variables. You can create a private repo for this directory and track the changes there. + +### Install Traefik + +Basic Traefik setup using docker compose. + +Create a file called `traefik.env` in `~/gitops` + +```shell +echo "TRAEFIK_DOMAIN=traefik.example.com" > ~/gitops/traefik.env +echo "EMAIL=admin@example.com" >> ~/gitops/traefik.env +echo "HASHED_PASSWORD=`openssl passwd -apr1 changeit`" >> ~/gitops/traefik.env +``` + +Note: + +- Change the domain from `traefik.example.com` to the one used in production. DNS entry needs to point to the Server IP. +- Change the letsencrypt notification email from `admin@example.com` to correct email. +- Change the password from `changeit` to more secure. + +env file generated at location `~/gitops/traefik.env` will look like following: + +```env +TRAEFIK_DOMAIN=traefik.example.com +EMAIL=admin@example.com +HASHED_PASSWORD=$apr1$K.4gp7RT$tj9R2jHh0D4Gb5o5fIAzm/ +``` + +Create a yaml file called `traefik.yaml` in `~/gitops` directory by downloading the traefik compose file. + +```shell +curl -sL https://raw.githubusercontent.com/frappe/frappe_docker/main/overrides/compose.traefik-docker.yaml -o ~/gitops/traefik.yaml +``` + +Deploy the traefik container + +```shell +docker compose --project-name traefik --env-file ~/gitops/traefik.env -f ~/gitops/traefik.yaml up -d +``` + +This will make the traefik dashboard available on `traefik.example.com` and all certificates will reside in `/data/traefik/certificates` on host filesystem. + +### Install MariaDB + +Basic MariaDB setup using docker compose. + +Create a file called `mariadb.env` in `~/gitops` + +```shell +echo "DB_PASSWORD=changeit" > ~/gitops/mariadb.env +``` + +Note: + +- Change the password from `changeit` to more secure. + +env file generated at location `~/gitops/mariadb.env` will look like following: + +```env +DB_PASSWORD=changeit +``` + +Note: Change the password from `changeit` to more secure one. + +Create a yaml file called `mariadb.yaml` in `~/gitops` directory by downloading the mariadb compose file. + +```shell +curl -sL https://raw.githubusercontent.com/frappe/frappe_docker/main/overrides/compose.mariadb-shared.yaml -o ~/gitops/mariadb.yaml +``` + +Deploy the mariadb container + +```shell +docker compose --project-name mariadb --env-file ~/gitops/mariadb.env -f ~/gitops/mariadb.yaml up -d +``` + +This will make `mariadb-database` service available under `mariadb-network`. Data will reside in `/data/mariadb`. + +### Install ERPNext + +Download the common files to generate templates into `~/gitops/overrides`: + +```shell +curl -sL https://raw.githubusercontent.com/frappe/frappe_docker/main/compose.yaml -o ~/gitops/overrides/compose.yaml +curl -sL https://raw.githubusercontent.com/frappe/frappe_docker/main/overrides/compose.erpnext.yaml -o ~/gitops/overrides/compose.erpnext.yaml +curl -sL https://raw.githubusercontent.com/frappe/frappe_docker/main/overrides/compose.redis.yaml -o ~/gitops/overrides/compose.redis.yaml +curl -sL https://raw.githubusercontent.com/frappe/frappe_docker/main/overrides/compose.multi-bench.yaml -o ~/gitops/overrides/compose.multi-bench.yaml +``` + +#### Create first bench + +Create second bench called `erpnext-one` with `one.example.com` and `two.example.com` + +Create a file called `erpnext-one.env` in `~/gitops` + +```shell +curl -sL https://raw.githubusercontent.com/frappe/frappe_docker/main/example.env -o ~/gitops/erpnext-one.env +sed -i 's/DB_PASSWORD=123/DB_PASSWORD=changeit/g' ~/gitops/erpnext-one.env +sed -i 's/DB_HOST=/DB_HOST=mariadb-database/g' ~/gitops/erpnext-one.env +sed -i 's/DB_PORT=/DB_PORT=3306/g' ~/gitops/erpnext-one.env +echo "ROUTER=erpnext-one" >> ~/gitops/erpnext-one.env +echo "SITES=\`one.example.com\`,\`two.example.com\`" >> ~/gitops/erpnext-one.env +``` + +Note: + +- Change the password from `changeit` to the one set for MariaDB compose in the previous step. + +env file is generated at location `~/gitops/erpnext-one.env`. + +Create a yaml file called `erpnext-one.yaml` in `~/gitops` directory: + +```shell +docker compose --project-name erpnext-one \ + --env-file ~/gitops/erpnext-one.env \ + -f ~/gitops/overrides/compose.yaml \ + -f ~/gitops/overrides/compose.erpnext.yaml \ + -f ~/gitops/overrides/compose.redis.yaml \ + -f ~/gitops/overrides/compose.multi-bench.yaml config > ~/gitops/erpnext-one.yaml +``` + +Use the above command after any changes are made to `erpnext-one.env` file to regenerate `~/gitops/erpnext-one.yaml`. e.g. after changing version to migrate the bench. + +Deploy `erpnext-one` containers: + +```shell +docker compose --project-name erpnext-one -f ~/gitops/erpnext-one.yaml up -d +``` + +Create sites `one.example.com` and `two.example.com`: + +```shell +# one.example.com +docker compose --project-name erpnext-one --env-file ~/gitops/erpnext-one.env exec backend \ + bench new-site one.example.com --mariadb-root-password changeit --install-app erpnext --admin-password changeit +``` + +You can stop here and have a single bench single site setup complete. Continue to add one more site to the current bench. + +```shell +# two.example.com +docker compose --project-name erpnext-one --env-file ~/gitops/erpnext-one.env exec backend \ + bench new-site two.example.com --mariadb-root-password changeit --install-app erpnext --admin-password changeit +``` + +#### Create second bench + +Setting up additional bench is optional. Continue only if you need multi bench setup. + +Create second bench called `erpnext-two` with `three.example.com` and `four.example.com` + +Create a file called `erpnext-two.env` in `~/gitops` + +```shell +curl -sL https://raw.githubusercontent.com/frappe/frappe_docker/main/example.env -o ~/gitops/erpnext-two.env +sed -i 's/DB_PASSWORD=123/DB_PASSWORD=changeit/g' ~/gitops/erpnext-two.env +sed -i 's/DB_HOST=/DB_HOST=mariadb-database/g' ~/gitops/erpnext-two.env +sed -i 's/DB_PORT=/DB_PORT=3306/g' ~/gitops/erpnext-two.env +echo "ROUTER=erpnext-two" >> ~/gitops/erpnext-two.env +echo "SITES=\`three.example.com\`,\`four.example.com\`" >> ~/gitops/erpnext-two.env +``` + +Note: + +- Change the password from `changeit` to the one set for MariaDB compose in the previous step. + +env file is generated at location `~/gitops/erpnext-two.env`. + +Create a yaml file called `erpnext-two.yaml` in `~/gitops` directory: + +```shell +docker compose --project-name erpnext-two \ + --env-file ~/gitops/erpnext-two.env \ + -f ~/gitops/overrides/compose.yaml \ + -f ~/gitops/overrides/compose.erpnext.yaml \ + -f ~/gitops/overrides/compose.redis.yaml \ + -f ~/gitops/overrides/compose.multi-bench.yaml config > ~/gitops/erpnext-two.yaml +``` + +Use the above command after any changes are made to `erpnext-two.env` file to regenerate `~/gitops/erpnext-two.yaml`. e.g. after changing version to migrate the bench. + +Deploy `erpnext-two` containers: + +```shell +docker compose --project-name erpnext-two -f ~/gitops/erpnext-two.yaml up -d +``` + +Create sites `three.example.com` and `four.example.com`: + +```shell +# three.example.com +docker compose --project-name erpnext-two --env-file ~/gitops/erpnext-two.env exec backend \ + bench new-site three.example.com --mariadb-root-password changeit --install-app erpnext --admin-password changeit +# four.example.com +docker compose --project-name erpnext-two --env-file ~/gitops/erpnext-two.env exec backend \ + bench new-site four.example.com --mariadb-root-password changeit --install-app erpnext --admin-password changeit +``` + +### Site operations + +Refer: [site operations](./site-operations.md) diff --git a/overrides/compose.mariadb-shared.yaml b/overrides/compose.mariadb-shared.yaml new file mode 100644 index 00000000..25e2e508 --- /dev/null +++ b/overrides/compose.mariadb-shared.yaml @@ -0,0 +1,26 @@ +version: "3.3" + +services: + database: + container_name: mariadb-database + image: mariadb:10.6 + healthcheck: + test: mysqladmin ping -h localhost --password=${DB_PASSWORD:-changeit} + interval: 1s + retries: 15 + command: + - --character-set-server=utf8mb4 + - --collation-server=utf8mb4_unicode_ci + - --skip-character-set-client-handshake + - --skip-innodb-read-only-compressed + environment: + MYSQL_ROOT_PASSWORD: ${DB_PASSWORD:-changeit} + volumes: + - /data/mariadb:/var/lib/mysql + networks: + - mariadb-network + +networks: + mariadb-network: + name: mariadb-network + external: false diff --git a/overrides/compose.multi-bench.yaml b/overrides/compose.multi-bench.yaml new file mode 100644 index 00000000..d6b2c5f2 --- /dev/null +++ b/overrides/compose.multi-bench.yaml @@ -0,0 +1,41 @@ +services: + frontend: + networks: + - traefik-public + - mariadb-network + labels: + - traefik.enable=true + - traefik.http.routers.${ROUTER?ROUTER not set}.rule=Host(${SITES?SITES not set}) + - traefik.http.routers.${ROUTER}.entrypoints=http,https + - traefik.http.routers.${ROUTER}.tls.certresolver=le + - traefik.http.services.${ROUTER}.loadbalancer.server.port=8080 + configurator: + networks: + - mariadb-network + backend: + networks: + - mariadb-network + websocket: + networks: + - mariadb-network + scheduler: + networks: + - mariadb-network + queue-default: + networks: + - mariadb-network + queue-short: + networks: + - mariadb-network + queue-long: + networks: + - mariadb-network + redis: + networks: + - mariadb-network + +networks: + traefik-public: + external: true + mariadb-network: + external: true diff --git a/overrides/compose.traefik-docker.yaml b/overrides/compose.traefik-docker.yaml new file mode 100644 index 00000000..0d569ec9 --- /dev/null +++ b/overrides/compose.traefik-docker.yaml @@ -0,0 +1,69 @@ +version: "3.3" + +services: + traefik: + image: "traefik:v2.6" + labels: + # Enable Traefik for this service, to make it available in the public network + - traefik.enable=true + # Use the traefik-public network (declared below) + - traefik.docker.network=traefik-public + # admin-auth middleware with HTTP Basic auth + # Using the environment variables USERNAME and HASHED_PASSWORD + - traefik.http.middlewares.admin-auth.basicauth.users=admin:${HASHED_PASSWORD:?No HASHED_PASSWORD set} + # https-redirect middleware to redirect HTTP to HTTPS + # It can be re-used by other stacks in other Docker Compose files + - traefik.http.middlewares.https-redirect.redirectscheme.scheme=https + - traefik.http.middlewares.https-redirect.redirectscheme.permanent=true + # traefik-http set up only to use the middleware to redirect to https + # Uses the environment variable DOMAIN + - traefik.http.routers.traefik-public-http.rule=Host(`${TRAEFIK_DOMAIN:?No TRAEFIK_DOMAIN set}`) + - traefik.http.routers.traefik-public-http.entrypoints=http + - traefik.http.routers.traefik-public-http.middlewares=https-redirect + # traefik-https the actual router using HTTPS + # Uses the environment variable DOMAIN + - traefik.http.routers.traefik-public-https.rule=Host(`${TRAEFIK_DOMAIN}`) + - traefik.http.routers.traefik-public-https.entrypoints=https + - traefik.http.routers.traefik-public-https.tls=true + # Use the special Traefik service api@internal with the web UI/Dashboard + - traefik.http.routers.traefik-public-https.service=api@internal + # Use the "le" (Let's Encrypt) resolver created below + - traefik.http.routers.traefik-public-https.tls.certresolver=le + # Enable HTTP Basic auth, using the middleware created above + - traefik.http.routers.traefik-public-https.middlewares=admin-auth + # Define the port inside of the Docker service to use + - traefik.http.services.traefik-public.loadbalancer.server.port=8080 + command: + # Enable Docker in Traefik, so that it reads labels from Docker services + - --providers.docker=true + # Do not expose all Docker services, only the ones explicitly exposed + - --providers.docker.exposedbydefault=false + # Create an entrypoint http listening on port 80 + - --entrypoints.http.address=:80 + # Create an entrypoint https listening on port 443 + - --entrypoints.https.address=:443 + # Create the certificate resolver le for Let's Encrypt, uses the environment variable EMAIL + - --certificatesresolvers.le.acme.email=${EMAIL:?No EMAIL set} + # Store the Let's Encrypt certificates in the mounted volume + - --certificatesresolvers.le.acme.storage=/certificates/acme.json + # Use the TLS Challenge for Let's Encrypt + - --certificatesresolvers.le.acme.tlschallenge=true + # Enable the access log, with HTTP requests + - --accesslog + # Enable the Traefik log, for configurations and errors + - --log + # Enable the Dashboard and API + - --api + ports: + - 80:80 + - 443:443 + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + - /data/traefik/certificates:/certificates + networks: + - traefik-public + +networks: + traefik-public: + name: traefik-public + external: false