Global refactoring (#617)
* Rename `bench-build` target to `bench` in bake file * Update bake file and break everything * Rename docker-compose.yml to compose.yml to avoid conflicting on `docker buildx bake` * Fix groups in bake file * Update frappe-worker * Update frappe-nginx, erpnext-nginx * Remove old erpnext images * Update frappe-socketio * Fix develop frappe-nginx build on linux/arm64 * Update dockerignore * Update gitignore * Update gitignore * Update .env files * Update installation (overrides) * Update tests * Fix image names * Update compose * Update get-latest-tags * Update CI * Setup and remove .env on tests * Add build bench workflow * Add triggers to main workflow * Add release helm job * Use reusable workflows * Rollback * Print configuration before running tests * Show tests/.env * Revert "Show tests/.env" This reverts commit4bc3bdebaf. * Fix ci image versions * Remove `frappe-` prefix in build directories * Move requirements-dev.txt * Fix image name in CI * Update gitignore * Update pre-commit config * Drop `version:` in compose files * Add push-backup * Fix postgres CI test * Change .yml to .yaml in compose file to follow compose-spec * Remove prettierignore * Fix dockerignore * Change .yml to .yaml in compose file to follow compose-spec * Don't depend on boto3 while testing (do it in backend) * Update erpnext example version * Don't fail ping on URLError * Move assets volume to main compose file * Fix type annotations for v12 * Fix postgres ci override in tests * Fix spaces in socketio * Reorder stages in nginx image, improve perfomance * Remove unused todo * Optimize worker build * Install Node in worker image * Add 502 error page * Remove unused quiet-pull in tests * Add configurator service to dynamically set common config * Remove unused compose.ci-postgres.yml * Use Python for configurator service: faster and more robust * Add TODO.md * Use python script to get latest tags in CI * Clean up nginx dockerfile * Remove VOLUME declaration https://stackoverflow.com/a/55052682 * Add custom app example * Remove pwd for now * Remove pwd for now * Use jq for parsing config in healthcheck * Take advantage of yaml lang: add defaults in compose file. Also require env vars * Fix CI * Use resusable workflow * Update * Move release_helm job to main.yml * Rename docker-build to docker-build-push * Rename main to build_stable * Rename bench targets * Remove quotes from docker-build-push inputs * Update build develop * Remove HELM_DEPLOY_KEY secret from docker-build-push * Add job names * Remove build_bench workflow * Update version input description in docker-build-push * Print .env in tests, if version is develop, change to latest (for tag) * Fix env setup * Uncomment tests * Parse and set short tags from git tag in bake file * Move devcontainer settings to devcontainer.json * Add db command notice * Fix CI? * Fix inconsistencies in development readme * Remove pwd for now * Remove custom apps for production instruction * Update todos * Add docs for images and compose files * Add variables docs and allow custom frappe site name header * Add notice about internal environment variables * Update site-operations docs * Update todos * Add Overrides header in images-and-compose-files * Update todos * Remove extra docs * Don't log requests in worker image (nginx already does that) * Remove default value of FRAPPE_SITE_NAME_HEADER in example.env * Use file that consistent in v12, v13 and develop to check /assets * Fix paths in CI * Update todos * Remove TODO.md * Update tests/_check_backup_files.py Co-authored-by: Revant Nandgaonkar <revant.one@gmail.com> * Change variables MINIO_ACCESS_KEY and MINIO_SECRET_KEY to S3_ACCESS_KEY, S3_SECRET_KEY in tests * Fix S3 test * Use `nginxinc/nginx-unprivileged` instead of `nginx` image Also use Ngnix 1.20 instead of unstable 1.21 * Fix https override * Update Dockerfile * Mount assets to backend service in read only mode * Touch .build (#307), use scripts from nginx image to generate config and touch .build * Update example env after building stable images * Touch `.build` on develop image (untill https://github.com/frappe/frappe/issues/15396 is resolved) * Add `make` to worker build deps for linux/arm64 * Fix update example.env job * Fix .build creation on develop branch * Move bench CI to different file This way workflow runs only on PRs that relevant to bench build * Fix app name in custom app example * Update erpnext and frappe versions in example.env * Don't install `svg-sprite` and `sass` node modules in nginx image on linux/arm64 (https://github.com/frappe/frappe/pull/15275) * docs: README and docs * docs: add link to site operations from docker swarm * ci: fix tests as per changes to compose.yaml * docs: move wiki articles to docs * docs: fix add custom domain * docs: fix patch code from images * fix: do not expose port 80 for old images * fix: custom domain labels to frontend container/service * Add missing descriptions to envs in example.env * Fix redis depends_on * Fix docker compose in tests when not running on TTY * Set -T flag in `docker compose exec` only if not tty * Run pre-commit on docs * Remove postgres healthcheck (it gets overriden by mariadb) * Refactor test * Update workflow names * Add pip to dependabot config * docs: backup and push (#19) * Beautify changes by @revant (#20) * feat: add gevent to worker image * feat: real_ip configuration for nginx * Return `healthcheck.sh` just for tests Co-authored-by: Lev Vereshchagin <mail@vrslev.com> * Make pretend bench catch unknown commands (closes #666) * Remove debug print in push-backup * Fix typing issues in push-backup * Update file keys in push-backups: from abs path to <site>/<file> * Refactor push-backup * Move gevent installation in Frappe step * Don't pin boto stubs requirement * Cache pip deps on build * Update example env versions * Refactor check backup files * Fix backup test * Fix backup test * Rename build/ dir to images/ * Rename build/ dir to images/ * Fix /build -> /images in docs * Update example.env * Use reusable workflow in frappe user instead of vrslev * Fix compose`s `project` option in docs (https://github.com/frappe/frappe_docker/pull/617#issuecomment-1065178792) * Add note about project option in site-operations doc * Update example env * Rename build arg `USERNAME` to `REGISTRY_USER` * Allow https proxy to access Docker socket * Revert "Use reusable workflow in frappe user instead of vrslev" This reverts commit6062500d0d. * Revert "Revert "Use reusable workflow in frappe user instead of vrslev"" This reverts commit4680d18ff8. Co-authored-by: Revant Nandgaonkar <revant.one@gmail.com>
This commit is contained in:
Lev
28
docs/add-custom-domain-using-traefik.md
Normal file
28
docs/add-custom-domain-using-traefik.md
Normal file
@@ -0,0 +1,28 @@
|
||||
Add following labels to `frontend` service
|
||||
|
||||
```yaml
|
||||
traefik.http.routers.custom-domain.rule: Host(`custom.localhost`)
|
||||
# Comment the entrypoints label if traefik already has default entrypoint set
|
||||
traefik.http.routers.custom-domain.entrypoints: web
|
||||
traefik.http.middlewares.custom-domain.headers.customrequestheaders.Host: mysite.localhost
|
||||
traefik.http.routers.custom-domain.middlewares: custom-domain
|
||||
# Add following header only if TLS is needed in case of live server
|
||||
traefik.http.routers.custom-domain.tls.certresolver: main-resolver
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
frontend:
|
||||
...
|
||||
labels:
|
||||
...
|
||||
traefik.http.routers.custom-domain.rule: Host(`custom.localhost`)
|
||||
traefik.http.routers.custom-domain.entrypoints: web
|
||||
traefik.http.middlewares.custom-domain.headers.customrequestheaders.Host: mysite.localhost
|
||||
traefik.http.routers.custom-domain.middlewares: custom-domain
|
||||
traefik.http.routers.custom-domain.tls.certresolver: main-resolver
|
||||
...
|
||||
```
|
||||
|
||||
This will add `custom.localhost` as custom domain for `mysite.localhost`
|
||||
63
docs/backup-and-push-cronjob.md
Normal file
63
docs/backup-and-push-cronjob.md
Normal file
@@ -0,0 +1,63 @@
|
||||
Create backup service or stack.
|
||||
|
||||
```yaml
|
||||
# backup-job.yml
|
||||
version: "3.7"
|
||||
services:
|
||||
backup:
|
||||
image: frappe/erpnext-worker:v13
|
||||
entrypoint: ["bash", "-c"]
|
||||
command: |
|
||||
for $SITE in $(/home/frappe/frappe-bench/env/bin/python -c "import frappe;print(' '.join(frappe.utils.get_sites()))")
|
||||
do
|
||||
bench --site $SITE backup --with-files
|
||||
push-backup \
|
||||
--site $SITE \
|
||||
--bucket $BUCKET_NAME \
|
||||
--region-name $REGION \
|
||||
--endpoint-url $ENDPOINT_URL \
|
||||
--aws-access-key-id $ACCESS_KEY_ID \
|
||||
--aws-secret-access-key $SECRET_ACCESS_KEY
|
||||
done
|
||||
environment:
|
||||
- BUCKET_NAME=erpnext
|
||||
- REGION=us-east-1
|
||||
- ACCESS_KEY_ID=RANDOMACCESSKEY
|
||||
- SECRET_ACCESS_KEY=RANDOMSECRETKEY
|
||||
- ENDPOINT_URL=https://endpoint.url
|
||||
volumes:
|
||||
- "sites-vol:/home/frappe/frappe-bench/sites"
|
||||
# Uncomment in case of Docker Swarm with crazy-max/swarm-cronjob
|
||||
# deploy:
|
||||
# labels:
|
||||
# - "swarm.cronjob.enable=true"
|
||||
# - "swarm.cronjob.schedule=0 */3 * * *"
|
||||
# - "swarm.cronjob.skip-running=true"
|
||||
# replicas: 0
|
||||
# restart_policy:
|
||||
# condition: none
|
||||
networks:
|
||||
- erpnext-network
|
||||
|
||||
networks:
|
||||
erpnext-network:
|
||||
external: true
|
||||
name: <your_frappe_docker_project_name>_default
|
||||
|
||||
volumes:
|
||||
sites-vol:
|
||||
external: true
|
||||
name: <your_frappe_docker_project_name>_sites-vol
|
||||
```
|
||||
|
||||
In case of single docker host setup, add crontab entry for backup every 6 hours.
|
||||
|
||||
```
|
||||
0 */6 * * * /usr/local/bin/docker-compose -f /path/to/backup-job.yml up -d > /dev/null
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Install [crazy-max/swarm-cronjob](https://github.com/crazy-max/swarm-cronjob) for docker swarm.
|
||||
- Uncomment `deploy` section in case of usage on docker swarm.
|
||||
- Change the cron string as per need.
|
||||
16
docs/bench-console-and-vscode-debugger.md
Normal file
16
docs/bench-console-and-vscode-debugger.md
Normal file
@@ -0,0 +1,16 @@
|
||||
Add the following configuration to `launch.json` `configurations` array to start bench console and use debugger. Replace `mysite.localhost` with appropriate site. Also replace `frappe-bench` with name of the bench directory.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Bench Console",
|
||||
"type": "python",
|
||||
"request": "launch",
|
||||
"program": "${workspaceFolder}/frappe-bench/apps/frappe/frappe/utils/bench_helper.py",
|
||||
"args": ["frappe", "--site", "mysite.localhost", "console"],
|
||||
"pythonPath": "${workspaceFolder}/frappe-bench/env/bin/python",
|
||||
"cwd": "${workspaceFolder}/frappe-bench/sites",
|
||||
"env": {
|
||||
"DEV_SERVER": "1"
|
||||
}
|
||||
}
|
||||
```
|
||||
16
docs/build-version-10-images.md
Normal file
16
docs/build-version-10-images.md
Normal file
@@ -0,0 +1,16 @@
|
||||
Clone the version-10 branch of this repo
|
||||
|
||||
```shell
|
||||
git clone https://github.com/frappe/frappe_docker.git -b version-10 && cd frappe_docker
|
||||
```
|
||||
|
||||
Build the images
|
||||
|
||||
```shell
|
||||
export DOCKER_REGISTRY_PREFIX=frappe
|
||||
docker build -t ${DOCKER_REGISTRY_PREFIX}/frappe-socketio:v10 -f build/frappe-socketio/Dockerfile .
|
||||
docker build -t ${DOCKER_REGISTRY_PREFIX}/frappe-nginx:v10 -f build/frappe-nginx/Dockerfile .
|
||||
docker build -t ${DOCKER_REGISTRY_PREFIX}/erpnext-nginx:v10 -f build/erpnext-nginx/Dockerfile .
|
||||
docker build -t ${DOCKER_REGISTRY_PREFIX}/frappe-worker:v10 -f build/frappe-worker/Dockerfile .
|
||||
docker build -t ${DOCKER_REGISTRY_PREFIX}/erpnext-worker:v10 -f build/erpnext-worker/Dockerfile .
|
||||
```
|
||||
@@ -0,0 +1,10 @@
|
||||
Not using separate container
|
||||
Add following to frappe container from the `.devcontainer/docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
extra_hosts:
|
||||
app1.localhost: 172.17.0.1
|
||||
app2.localhost: 172.17.0.1
|
||||
```
|
||||
|
||||
This is makes the domain names `app1.localhost` and `app2.localhost` connect to docker host and connect to services running on `localhost`.
|
||||
@@ -1,58 +0,0 @@
|
||||
# Custom apps
|
||||
|
||||
To add your own Frappe/ERPNext apps to the image, we'll need to create a custom image with the help of a unique wrapper script
|
||||
|
||||
> For the sake of simplicity, in this example, we'll be using a place holder called `[custom]`, and we'll be building off the edge image.
|
||||
|
||||
Create two directories called `[custom]-worker` and `[custom]-nginx` in the `build` directory.
|
||||
|
||||
```shell
|
||||
cd frappe_docker
|
||||
mkdir ./build/[custom]-worker ./build/[custom]-nginx
|
||||
```
|
||||
|
||||
Create a `Dockerfile` in `./build/[custom]-worker` with the following content:
|
||||
|
||||
```Dockerfile
|
||||
FROM frappe/erpnext-worker:edge
|
||||
|
||||
RUN install_app [custom] https://github.com/[username]/[custom] [branch]
|
||||
# Only add the branch if you are using a specific tag or branch.
|
||||
```
|
||||
|
||||
**Note:** Replace `https://github.com/[username]/[custom]` above with your custom app's Git repository URL (may include credentials if needed). Your custom app Git repository **must** be named exactly as the custom app's name, and use the same branch name as Frappe/ERPNext branch name that you use.
|
||||
|
||||
Create a `Dockerfile` in `./build/[custom]-nginx` with the following content:
|
||||
|
||||
```Dockerfile
|
||||
FROM bitnami/node:12-prod
|
||||
|
||||
COPY build/[custom]-nginx/install_app.sh /install_app
|
||||
|
||||
RUN /install_app [custom] https://github.com/[username]/[custom] [branch]
|
||||
|
||||
FROM frappe/erpnext-nginx:edge
|
||||
|
||||
COPY --from=0 /home/frappe/frappe-bench/sites/ /var/www/html/
|
||||
COPY --from=0 /rsync /rsync
|
||||
RUN echo -n "\n[custom]" >> /var/www/html/apps.txt
|
||||
|
||||
VOLUME [ "/assets" ]
|
||||
|
||||
ENTRYPOINT ["/docker-entrypoint.sh"]
|
||||
CMD ["nginx", "-g", "daemon off;"]
|
||||
```
|
||||
|
||||
Copy over the `install_app.sh` file from `./build/erpnext-nginx`
|
||||
|
||||
```shell
|
||||
cp ./build/erpnext-nginx/install_app.sh ./build/[custom]-nginx
|
||||
```
|
||||
|
||||
Open up `./installation/docker-compose-custom.yml` and replace all instances of `[app]` with the name of your app.
|
||||
|
||||
```shell
|
||||
sed -i "s#\[app\]#[custom]#" ./installation/docker-compose-custom.yml
|
||||
```
|
||||
|
||||
Install like usual, except that when you set the `INSTALL_APPS` variable to `erpnext,[custom]`.
|
||||
@@ -1,295 +1,55 @@
|
||||
### 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
|
||||
|
||||
### Create Config
|
||||
|
||||
Configs > Add Config > `frappe-mariadb-config`
|
||||
|
||||
```
|
||||
[mysqld]
|
||||
character-set-client-handshake = FALSE
|
||||
character-set-server = utf8mb4
|
||||
collation-server = utf8mb4_unicode_ci
|
||||
|
||||
[mysql]
|
||||
default-character-set = utf8mb4
|
||||
```bash
|
||||
docker-compose -f compose.yaml \
|
||||
-f overrides/compose.erpnext.yaml \
|
||||
-f overrides/compose.swarm.yaml \
|
||||
-f overrides/compose.https.yaml \
|
||||
config \
|
||||
| yq eval 'del(.services.*.depends_on) | del(.services.frontend.labels)' - \
|
||||
| yq eval '.services.proxy.command += "--providers.docker.swarmmode"' - > \
|
||||
~/gitops/compose.yaml
|
||||
```
|
||||
|
||||
### 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`
|
||||
|
||||
```
|
||||
longsecretpassword
|
||||
```bash
|
||||
# Setup Bench $BENCH_SUFFIX
|
||||
export BENCH_SUFFIX=one
|
||||
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.
|
||||
It is only available in mariadb containers at location `/run/secrets/frappe-mariadb-root-password` later
|
||||
Commands explained:
|
||||
|
||||
### 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:
|
||||
|
||||
```yaml
|
||||
version: "3.7"
|
||||
- Set `BENCH_SUFFIX` to the stack name. the stack will be located at `~/gitops/compose-${BENCH_SUFFIX}.yaml`.
|
||||
- `traefik-public` is assumed to be the network for traefik loadbalancer for swarm.
|
||||
- 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
|
||||
#### Site Operations
|
||||
|
||||
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
|
||||
Refer [site operations documentation](./site-operations) to create new site, migrate site, drop site and perform other site operations.
|
||||
|
||||
@@ -1,33 +0,0 @@
|
||||
List of environment variables for containers
|
||||
|
||||
### frappe-worker and erpnext-worker
|
||||
|
||||
Following environment variables are set into sites volume as `common_site_config.json`. It means once the file is created in volume, the variables won't have any effect, you need to edit the common_site_config.json to update the configuration
|
||||
|
||||
- `DB_HOST`: MariaDB host, domain name or ip address.
|
||||
- `DB_PORT`: MariaDB port.
|
||||
- `REDIS_CACHE`: Redis cache host, domain name or ip address.
|
||||
- `REDIS_QUEUE`: Redis queue host, domain name or ip address.
|
||||
- `REDIS_SOCKETIO`: Redis queue host, domain name or ip address.
|
||||
- `SOCKETIO_PORT: `: Port on which the SocketIO should start.
|
||||
- `WORKER_CLASS`: Optionally set gunicorn worker-class. Supports gevent only, defaults to gthread.
|
||||
|
||||
### frappe-nginx and erpnext-nginx
|
||||
|
||||
These variables are set on every container start. Change in these variables will reflect on every container start.
|
||||
|
||||
- `FRAPPE_PY`: Gunicorn host to reverse proxy. Default: 0.0.0.0
|
||||
- `FRAPPE_PY_PORT`: Gunicorn port to reverse proxy. Default: 8000
|
||||
- `FRAPPE_SOCKETIO`: SocketIO host to reverse proxy. Default: 0.0.0.0
|
||||
- `SOCKETIO_PORT`: SocketIO port to reverse proxy. Default: 9000
|
||||
- `HTTP_TIMEOUT`: Nginx http timeout. Default: 120
|
||||
- `UPSTREAM_REAL_IP_ADDRESS `: The trusted address (or ip range) of upstream proxy servers. If set, this will tell nginx to trust the X-Forwarded-For header from these proxy servers in determining the real IP address of connecting clients. Default: 127.0.0.1
|
||||
- `UPSTREAM_REAL_IP_RECURSIVE`: When set to `on`, this will tell nginx to not just look to the last upstream proxy server in determining the real IP address. Default: off
|
||||
- `UPSTREAM_REAL_IP_HEADER`: Set this to the header name sent by your upstream proxy server to indicate the real IP of connecting clients. Default: X-Forwarded-For
|
||||
- `FRAPPE_SITE_NAME_HEADER`: NGINX `X-Frappe-Site-Name` header in the HTTP request which matches a site name. Default: `$host`
|
||||
- `HTTP_HOST`: NGINX `Host` header in the HTTP request which matches a site name. Default: `$http_host`
|
||||
- `SKIP_NGINX_TEMPLATE_GENERATION`: When set to `1`, this will not generate a default NGINX configuration. The config file must be mounted inside the container (`/etc/nginx/conf.d`) by the user in this case. Default: `0`
|
||||
|
||||
### frappe-socketio
|
||||
|
||||
This container takes configuration from `common_site_config.json` which is already created by erpnext gunicorn container. It doesn't use any environment variables.
|
||||
100
docs/images-and-compose-files.md
Normal file
100
docs/images-and-compose-files.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# Images
|
||||
|
||||
There's 4 images that you can find in `/images` 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 our 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
|
||||
|
||||
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](https://werkzeug.palletsprojects.com/en/2.0.x/).
|
||||
- `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`. 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.
|
||||
- `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/).
|
||||
|
||||
## Overrides
|
||||
|
||||
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.https.yaml`. Automatically sets up Let's Encrypt certificate and redirects all requests to directed to http, to https.
|
||||
- `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:
|
||||
|
||||
```bash
|
||||
# Point to main compose file (compose.yaml) and add one more.
|
||||
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.
|
||||
|
||||
## 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](https://github.com/frappe/frappe/releases).
|
||||
|
||||
### `DB_PASSWORD`
|
||||
|
||||
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 [release](https://github.com/frappe/frappe/releases). 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`.
|
||||
|
||||
There is other variables not mentioned here. They're somewhat internal and you don't have to worry about them except you want to change main compose 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
|
||||
```
|
||||
10
docs/patch-code-from-images.md
Normal file
10
docs/patch-code-from-images.md
Normal file
@@ -0,0 +1,10 @@
|
||||
Example: https://discuss.erpnext.com/t/sms-two-factor-authentication-otp-msg-change/47835
|
||||
|
||||
Above example needs following Dockerfile based patch
|
||||
|
||||
```Dockerfile
|
||||
FROM frappe/erpnext-worker:v12.17.0
|
||||
|
||||
RUN /home/frappe/frappe-bench/env/bin/pip -e /home/frappe/frappe-bench/apps/custom_app
|
||||
RUN sed -i -e "s/Your verification code is/আপনার লগইন কোড/g" /home/frappe/frappe-bench/apps/frappe/frappe/twofactor.py
|
||||
```
|
||||
47
docs/port-based-multi-tenancy.md
Normal file
47
docs/port-based-multi-tenancy.md
Normal file
@@ -0,0 +1,47 @@
|
||||
WARNING: Do not use this in production if the site is going to be served over plain http.
|
||||
|
||||
### Step 1
|
||||
|
||||
Remove the traefik service from docker-compose.yml
|
||||
|
||||
### Step 2
|
||||
|
||||
Create nginx config file `/opt/nginx/conf/serve-8001.conf`:
|
||||
|
||||
```
|
||||
server {
|
||||
listen 8001;
|
||||
server_name $http_host;
|
||||
|
||||
location / {
|
||||
|
||||
rewrite ^(.+)/$ $1 permanent;
|
||||
rewrite ^(.+)/index\.html$ $1 permanent;
|
||||
rewrite ^(.+)\.html$ $1 permanent;
|
||||
|
||||
proxy_set_header X-Frappe-Site-Name mysite.localhost;
|
||||
proxy_set_header Host mysite.localhost;
|
||||
proxy_pass http://erpnext-nginx;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Replace the port with any port of choice e.g. `listen 4200;`
|
||||
- Change `mysite.localhost` to site name
|
||||
- Repeat the server blocks for multiple ports and site names to get the effect of port based multi tenancy
|
||||
|
||||
### Step 3
|
||||
|
||||
Run the docker container
|
||||
|
||||
```shell
|
||||
docker run --network=<project-name>_default \
|
||||
-p 8001:8001 \
|
||||
--volume=/opt/nginx/conf/serve-8001.conf:/etc/nginx/conf.d/default.conf -d nginx
|
||||
```
|
||||
|
||||
Note: Change the volumes, network and ports as needed
|
||||
|
||||
With the above example configured site will be accessible on `http://localhost:8001`
|
||||
96
docs/setup-options.md
Normal file
96
docs/setup-options.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# 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-name <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-name <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-name <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-name <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-name <project-name> -f ~/gitops/docker-compose.yml pull
|
||||
|
||||
# Restart containers
|
||||
docker-compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
|
||||
```
|
||||
|
||||
To migrate sites refer [site operations](./site-operations.md#migrate-site)
|
||||
@@ -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-apps-for-production.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: assets-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
|
||||
```
|
||||
@@ -1,177 +1,41 @@
|
||||
# Site operations
|
||||
|
||||
Create and use env file to pass environment variables to containers,
|
||||
> 💡 You should setup `--project-name` option in `docker-compose` commands if you have non-standard project name.
|
||||
|
||||
```sh
|
||||
source .env
|
||||
```
|
||||
|
||||
Or specify environment variables instead of passing secrets as command arguments. Refer notes section for environment variables required
|
||||
|
||||
## Setup New Site
|
||||
## Setup new site
|
||||
|
||||
Note:
|
||||
|
||||
- Wait for the database service to start before trying to create a new site.
|
||||
- If new site creation fails, retry after the MariaDB container is up and running.
|
||||
- If you're using a managed database instance, make sure that the database is running before setting up a new site.
|
||||
|
||||
#### MariaDB Site
|
||||
- Wait for the `db` service to start and `configurator` to exit before trying to create a new site. Usually this takes up to 10 seconds.
|
||||
|
||||
```sh
|
||||
# Create ERPNext site
|
||||
docker run \
|
||||
-e "SITE_NAME=$SITE_NAME" \
|
||||
-e "DB_ROOT_USER=$DB_ROOT_USER" \
|
||||
-e "MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD" \
|
||||
-e "ADMIN_PASSWORD=$ADMIN_PASSWORD" \
|
||||
-e "INSTALL_APPS=erpnext" \
|
||||
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
|
||||
--network <project-name>_default \
|
||||
frappe/erpnext-worker:$ERPNEXT_VERSION new
|
||||
docker-compose exec backend bench new-site <site-name> --mariadb-root-password <db-password> --admin-password <admin-password>
|
||||
```
|
||||
|
||||
#### PostgreSQL Site
|
||||
If you need to install some app, specify `--install-app`. To see all options, just run `bench new-site --help`.
|
||||
|
||||
PostgreSQL is only available v12 onwards. It is NOT available for ERPNext.
|
||||
It is available as part of `frappe/erpnext-worker`. It inherits from `frappe/frappe-worker`.
|
||||
To create Postgres site (assuming you already use [Postgres compose override](images-and-compose-files.md#overrides)) you need have to do set `root_login` and `root_password` in common config before that:
|
||||
|
||||
```sh
|
||||
# Create ERPNext site
|
||||
docker run \
|
||||
-e "SITE_NAME=$SITE_NAME" \
|
||||
-e "DB_ROOT_USER=$DB_ROOT_USER" \
|
||||
-e "POSTGRES_HOST=$POSTGRES_HOST" \
|
||||
-e "POSTGRES_PASSWORD=$POSTGRES_PASSWORD" \
|
||||
-e "ADMIN_PASSWORD=$ADMIN_PASSWORD" \
|
||||
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
|
||||
--network <project-name>_default \
|
||||
frappe/erpnext-worker:$ERPNEXT_VERSION new
|
||||
docker-compose exec backend bench set-config -g root_login <root-login>
|
||||
docker-compose exec backend bench set-config -g root_password <root-password>
|
||||
```
|
||||
|
||||
Environment Variables needed:
|
||||
|
||||
- `SITE_NAME`: name of the new site to create. Site name is domain name that resolves. e.g. `erp.example.com` or `erp.localhost`.
|
||||
- `DB_ROOT_USER`: MariaDB/PostgreSQL Root user.
|
||||
- `MYSQL_ROOT_PASSWORD`: In case of the MariaDB docker container use the one set in `MYSQL_ROOT_PASSWORD` in previous steps. In case of a managed database use the appropriate password.
|
||||
- `MYSQL_ROOT_PASSWORD_FILE` - When the MariaDB root password is stored using docker secrets.
|
||||
- `ADMIN_PASSWORD`: set the administrator password for the new site.
|
||||
- `ADMIN_PASSWORD_FILE`: set the administrator password for the new site using docker secrets.
|
||||
- `INSTALL_APPS=erpnext`: available only in erpnext-worker and erpnext containers (or other containers with custom apps). Installs ERPNext (and/or the specified apps, comma-delinieated) on this new site.
|
||||
- `FORCE=1`: optional variable which force installation of the same site.
|
||||
|
||||
Environment Variables for PostgreSQL only:
|
||||
|
||||
- `POSTGRES_HOST`: host for PostgreSQL server
|
||||
- `POSTGRES_PASSWORD`: Password for `postgres`. The database root user.
|
||||
|
||||
Notes:
|
||||
|
||||
- To setup existing frappe-bench deployment with default database as PostgreSQL edit the common_site_config.json and set `db_host` to PostgreSQL hostname and `db_port` to PostgreSQL port.
|
||||
- To create new frappe-bench deployment with default database as PostgreSQL use `POSTGRES_HOST` and `DB_PORT` environment variables in `erpnext-python` service instead of `MARIADB_HOST`
|
||||
|
||||
## Add sites to proxy
|
||||
|
||||
Change `SITES` variable to the list of sites created encapsulated in backtick and separated by comma with no space. e.g. `` SITES=`site1.example.com`,`site2.example.com` ``.
|
||||
|
||||
Reload variables with following command.
|
||||
Also command is slightly different:
|
||||
|
||||
```sh
|
||||
docker-compose --project-name <project-name> up -d
|
||||
docker-compose exec backend bench new-site <site-name> --db-type postgres --admin-password <admin-password>
|
||||
```
|
||||
|
||||
## Backup Sites
|
||||
## Push backup to S3 storage
|
||||
|
||||
Environment Variables
|
||||
|
||||
- `SITES` is list of sites separated by `:` colon to migrate. e.g. `SITES=site1.domain.com` or `SITES=site1.domain.com:site2.domain.com` By default all sites in bench will be backed up.
|
||||
- `WITH_FILES` if set to 1, it will backup user-uploaded files.
|
||||
- By default `backup` takes mariadb dump and gzips it. Example file, `20200325_221230-test_localhost-database.sql.gz`
|
||||
- If `WITH_FILES` is set then it will also backup public and private files of each site as uncompressed tarball. Example files, `20200325_221230-test_localhost-files.tar` and `20200325_221230-test_localhost-private-files.tar`
|
||||
- All the files generated by backup are placed at volume location `sites-vol:/{site-name}/private/backups/*`
|
||||
We have the script that helps to push latest backup to S3.
|
||||
|
||||
```sh
|
||||
docker run \
|
||||
-e "SITES=site1.domain.com:site2.domain.com" \
|
||||
-e "WITH_FILES=1" \
|
||||
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
|
||||
--network <project-name>_default \
|
||||
frappe/erpnext-worker:$ERPNEXT_VERSION backup
|
||||
docker-compose exec backend push_backup.py --site-name <site-name> --bucket <bucket> --region-name <region> --endpoint-url <endpoint-url> --aws-access-key-id <access-key> --aws-secret-access-key <secret-key>
|
||||
```
|
||||
|
||||
The backup will be available in the `sites-vol` volume.
|
||||
|
||||
## Push backup to s3 compatible storage
|
||||
|
||||
Environment Variables
|
||||
|
||||
- `BUCKET_NAME`, Required to set bucket created on S3 compatible storage.
|
||||
- `REGION`, Required to set region for S3 compatible storage.
|
||||
- `ACCESS_KEY_ID`, Required to set access key.
|
||||
- `SECRET_ACCESS_KEY`, Required to set secret access key.
|
||||
- `ENDPOINT_URL`, Required to set URL of S3 compatible storage.
|
||||
- `BUCKET_DIR`, Required to set directory in bucket where sites from this deployment will be backed up.
|
||||
- `BACKUP_LIMIT`, Optionally set this to limit number of backups in bucket directory. Defaults to 3.
|
||||
|
||||
```sh
|
||||
docker run \
|
||||
-e "BUCKET_NAME=backups" \
|
||||
-e "REGION=region" \
|
||||
-e "ACCESS_KEY_ID=access_id_from_provider" \
|
||||
-e "SECRET_ACCESS_KEY=secret_access_from_provider" \
|
||||
-e "ENDPOINT_URL=https://region.storage-provider.com" \
|
||||
-e "BUCKET_DIR=frappe-bench" \
|
||||
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
|
||||
--network <project-name>_default \
|
||||
frappe/frappe-worker:$FRAPPE_VERSION push-backup
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
- Above example will backup files in bucket called `backup` at location `frappe-bench-v13/site.name.com/DATE_TIME/DATE_TIME-site_name_com-{filetype}.{extension}`,
|
||||
- example DATE_TIME: 20200325_042020.
|
||||
- example filetype: database, files or private-files
|
||||
- example extension: sql.gz or tar
|
||||
|
||||
## Restore backups
|
||||
|
||||
Environment Variables
|
||||
|
||||
- `MYSQL_ROOT_PASSWORD` or `MYSQL_ROOT_PASSWORD_FILE`(when using docker secrets), Required to restore mariadb backups.
|
||||
- `BUCKET_NAME`, Required to set bucket created on S3 compatible storage.
|
||||
- `ACCESS_KEY_ID`, Required to set access key.
|
||||
- `SECRET_ACCESS_KEY`, Required to set secret access key.
|
||||
- `ENDPOINT_URL`, Required to set URL of S3 compatible storage.
|
||||
- `REGION`, Required to set region for s3 compatible storage.
|
||||
- `BUCKET_DIR`, Required to set directory in bucket where sites from this deployment will be backed up.
|
||||
|
||||
```sh
|
||||
docker run \
|
||||
-e "MYSQL_ROOT_PASSWORD=admin" \
|
||||
-e "BUCKET_NAME=backups" \
|
||||
-e "REGION=region" \
|
||||
-e "ACCESS_KEY_ID=access_id_from_provider" \
|
||||
-e "SECRET_ACCESS_KEY=secret_access_from_provider" \
|
||||
-e "ENDPOINT_URL=https://region.storage-provider.com" \
|
||||
-e "BUCKET_DIR=frappe-bench" \
|
||||
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
|
||||
-v ./backups:/home/frappe/backups \
|
||||
--network <project-name>_default \
|
||||
frappe/frappe-worker:$FRAPPE_VERSION restore-backup
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
- Volume must be mounted at location `/home/frappe/backups` for restoring sites
|
||||
- If no backup files are found in volume, it will use s3 credentials to pull backups
|
||||
- Backup structure for mounted volume or downloaded from s3:
|
||||
- /home/frappe/backups
|
||||
- site1.domain.com
|
||||
- 20200420_162000
|
||||
- 20200420_162000-site1_domain_com-\*
|
||||
- site2.domain.com
|
||||
- 20200420_162000
|
||||
- 20200420_162000-site2_domain_com-\*
|
||||
Note that you can restore backup only manually.
|
||||
|
||||
## Edit configs
|
||||
|
||||
@@ -179,12 +43,11 @@ Editing config manually might be required in some cases,
|
||||
one such case is to use Amazon RDS (or any other DBaaS).
|
||||
For full instructions, refer to the [wiki](<https://github.com/frappe/frappe/wiki/Using-Frappe-with-Amazon-RDS-(or-any-other-DBaaS)>). Common question can be found in Issues and on forum.
|
||||
|
||||
`common_site_config.json` or `site_config.json` from `sites-vol` volume has to be edited using following command:
|
||||
`common_site_config.json` or `site_config.json` from `sites` volume has to be edited using following command:
|
||||
|
||||
```sh
|
||||
docker run \
|
||||
-it \
|
||||
-v <project-name>_sites-vol:/sites \
|
||||
docker run --rm -it \
|
||||
-v <project-name>_sites:/sites \
|
||||
alpine vi /sites/common_site_config.json
|
||||
```
|
||||
|
||||
@@ -195,8 +58,7 @@ Instead of `alpine` use any image of your choice.
|
||||
For socketio and gunicorn service ping the hostname:port and that will be sufficient. For workers and scheduler, there is a command that needs to be executed.
|
||||
|
||||
```shell
|
||||
docker exec -it <project-name>_erpnext-worker-d \
|
||||
docker-entrypoint.sh doctor -p postgresql:5432 --ping-service mongodb:27017
|
||||
docker-compose exec backend healthcheck.sh --ping-service mongodb:27017
|
||||
```
|
||||
|
||||
Additional services can be pinged as part of health check with option `-p` or `--ping-service`.
|
||||
@@ -204,86 +66,20 @@ Additional services can be pinged as part of health check with option `-p` or `-
|
||||
This check ensures that given service should be connected along with services in common_site_config.json.
|
||||
If connection to service(s) fails, the command fails with exit code 1.
|
||||
|
||||
## Frappe internal commands using bench helper
|
||||
---
|
||||
|
||||
To execute commands using bench helper.
|
||||
|
||||
```shell
|
||||
docker run \
|
||||
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
|
||||
--network <project-name>_default \
|
||||
--user frappe \
|
||||
frappe/frappe-worker:$FRAPPE_VERSION bench --help
|
||||
```
|
||||
|
||||
Example command to clear cache
|
||||
|
||||
```shell
|
||||
docker run \
|
||||
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
|
||||
--network <project-name>_default \
|
||||
--user frappe \
|
||||
frappe/frappe-worker:$FRAPPE_VERSION bench --site erp.mysite.com clear-cache
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Use it to install/uninstall custom apps, add system manager user, etc.
|
||||
- To run the command as non root user add the command option `--user frappe`.
|
||||
|
||||
## Delete/Drop Site
|
||||
|
||||
#### MariaDB Site
|
||||
For reference of commands like `backup`, `drop-site` or `migrate` check [official guide](https://frappeframework.com/docs/v13/user/en/bench/frappe-commands) or run:
|
||||
|
||||
```sh
|
||||
# Delete/Drop ERPNext site
|
||||
docker run \
|
||||
-e "SITE_NAME=$SITE_NAME" \
|
||||
-e "DB_ROOT_USER=$DB_ROOT_USER" \
|
||||
-e "MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD" \
|
||||
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
|
||||
--network <project-name>_default \
|
||||
frappe/erpnext-worker:$ERPNEXT_VERSION drop
|
||||
docker-compose exec backend bench --help
|
||||
```
|
||||
|
||||
#### PostgreSQL Site
|
||||
## 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
|
||||
# Delete/Drop ERPNext site
|
||||
docker run \
|
||||
-e "SITE_NAME=$SITE_NAME" \
|
||||
-e "DB_ROOT_USER=$DB_ROOT_USER" \
|
||||
-e "POSTGRES_PASSWORD=$POSTGRES_PASSWORD" \
|
||||
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
|
||||
--network <project-name>_default \
|
||||
frappe/erpnext-worker:$ERPNEXT_VERSION drop
|
||||
docker-compose exec backend bench --site <site-name> migrate
|
||||
```
|
||||
|
||||
Environment Variables needed:
|
||||
|
||||
- `SITE_NAME`: name of the site to be deleted. Site name is domain name that resolves. e.g. `erp.example.com` or `erp.localhost`.
|
||||
- `DB_ROOT_USER`: MariaDB/PostgreSQL Root user.
|
||||
- `MYSQL_ROOT_PASSWORD`: Root User password for MariaDB.
|
||||
- `FORCE=1`: optional variable which force deletion of the same site.
|
||||
- `NO_BACKUP=1`: option variable to skip the process of taking backup before deleting the site.
|
||||
|
||||
Environment Variables for PostgreSQL only:
|
||||
|
||||
- `POSTGRES_PASSWORD`: Password for `postgres`. The database root user.
|
||||
|
||||
## Migrate Site
|
||||
|
||||
```sh
|
||||
# Migrate ERPNext site
|
||||
docker run \
|
||||
-e "MAINTENANCE_MODE=1" \
|
||||
-v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
|
||||
-v <project-name>_assets-vol:/home/frappe/frappe-bench/sites/assets \
|
||||
--network <project-name>_default \
|
||||
frappe/erpnext-worker:$ERPNEXT_VERSION migrate
|
||||
```
|
||||
|
||||
Environment Variables needed:
|
||||
|
||||
- `MAINTENANCE_MODE`: If set to `1`, this will ensure the bench is switched to maintenance mode during migration.
|
||||
- `SITES`: Optional list of sites to be migrated, separated by colon (`:`). e.g. `erp.site1.com:erp.site2.com`. If not used, all sites will be migrated by default.
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
# Tips for moving deployments
|
||||
|
||||
- Take regular automatic backups and push the files to S3 compatible cloud. Setup backup and push with cronjobs
|
||||
- Use regular cron for single machine installs
|
||||
- Use [swarm-cronjob](https://github.com/crazy-max/swarm-cronjob) for docker swarm
|
||||
- Use Kubernetes CronJob
|
||||
- It makes it easy to transfer data from cloud to any new deployment.
|
||||
- They are just [site operations](site-operations.md) that can be manually pipelined as per need.
|
||||
- Remember to restore encryption keys and other custom configuration from `site_config.json`.
|
||||
- Steps to move deployment:
|
||||
- [Take backup](site-operations.md#backup-sites)
|
||||
- [Push backup to cloud](site-operations.md#push-backup-to-s3-compatible-storage)
|
||||
- Create new deployment type anywhere
|
||||
- [Restore backup from cloud](site-operations.md#restore-backups)
|
||||
- [Restore `site_config.json` from cloud](site-operations.md#edit-configs)
|
||||
55
docs/troubleshoot.md
Normal file
55
docs/troubleshoot.md
Normal file
@@ -0,0 +1,55 @@
|
||||
1. [Fixing MariaDB issues after rebuilding the container](#fixing-mariadb-issues-after-rebuilding-the-container)
|
||||
1. [Letsencrypt companion not working](#letsencrypt-companion-not-working)
|
||||
1. [docker-compose does not recognize variables from `.env` file](#docker-compose-does-not-recognize-variables-from-env-file)
|
||||
1. [Windows Based Installation](#windows-based-installation)
|
||||
|
||||
### Fixing MariaDB issues after rebuilding the container
|
||||
|
||||
For any reason after rebuilding the container if you are not be able to access MariaDB correctly with the previous configuration. Follow these instructions.
|
||||
|
||||
The parameter `'db_name'@'%'` needs to be set in MariaDB and permission to the site database suitably assigned to the user.
|
||||
|
||||
This step has to be repeated for all sites available under the current bench.
|
||||
Example shows the queries to be executed for site `localhost`
|
||||
|
||||
Open sites/localhost/site_config.json:
|
||||
|
||||
```shell
|
||||
code sites/localhost/site_config.json
|
||||
```
|
||||
|
||||
and take note of the parameters `db_name` and `db_password`.
|
||||
|
||||
Enter MariaDB Interactive shell:
|
||||
|
||||
```shell
|
||||
mysql -uroot -p123 -hmariadb
|
||||
```
|
||||
|
||||
Execute following queries replacing `db_name` and `db_password` with the values found in site_config.json.
|
||||
|
||||
```sql
|
||||
UPDATE mysql.user SET Host = '%' where User = 'db_name'; FLUSH PRIVILEGES;
|
||||
SET PASSWORD FOR 'db_name'@'%' = PASSWORD('db_password'); FLUSH PRIVILEGES;
|
||||
GRANT ALL PRIVILEGES ON `db_name`.* TO 'db_name'@'%'; FLUSH PRIVILEGES;
|
||||
EXIT;
|
||||
```
|
||||
|
||||
### Letsencrypt companion not working
|
||||
|
||||
- Nginx Letsencrypt Companion needs to be setup before starting ERPNext services.
|
||||
- Are domain names in `SITES` variable correct?
|
||||
- Is DNS record configured? `A Name` record needs to point to Public IP of server.
|
||||
- Try Restarting containers.
|
||||
|
||||
### docker-compose does not recognize variables from `.env` file
|
||||
|
||||
If you are using old version of `docker-compose` the .env file needs to be located in directory from where the docker-compose command is executed. There may also be difference in official `docker-compose` and the one packaged by distro.
|
||||
|
||||
### Windows Based Installation
|
||||
|
||||
- Set environment variable `COMPOSE_CONVERT_WINDOWS_PATHS` e.g. `set COMPOSE_CONVERT_WINDOWS_PATHS=1`
|
||||
- Make the `frappe-mariadb.cnf` read-only for mariadb container to pick it up.
|
||||
- While using docker machine, port-forward the port 80 of VM to port 80 of host machine
|
||||
- Name all the sites ending with `.localhost`. and access it via browser locally. e.g. `http://site1.localhost`
|
||||
- related issue comment https://github.com/frappe/frappe_docker/issues/448#issuecomment-851723912
|
||||
Reference in New Issue
Block a user