accounting/frappe_docker
2
0
Fork 0
mirror of https://github.com/frappe/frappe_docker.git synced 2025-01-06 23:43:59 +00:00
Code Issues Releases Activity

docs: move wiki articles to docs

Browse Source
This commit is contained in:
Revant Nandgaonkar 2022-01-10 14:10:25 +05:30
parent 73f3d453c4
commit 8f814e5f5d
10 changed files with 328 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
README.md
View File

@ -28,6 +28,15 @@ Also, there's docs to help with deployment:
- [Docker Swarm](docs/docker-swarm.md),
- [Kubernetes (frappe/helm)](https://helm.erpnext.com),
- [site operations](docs/site-operations.md).
- Other
- [add custom domain using traefik](docs/add-custom-domain-using-traefik.md)
- [backup and push cron jobs](docs/backup-and-push-cronjob.md)
- [bench console and vscode debugger](docs/bench-console-and-vscode-debugger.md)
- [build version 10](docs/build-version-10-images.md)
- [connect to localhost services from containers for local app development](docs/connect-to-localhost-services-from-containers-for-local-app-development.md)
- [patch code from images](docs/patch-code-from-images.md)
- [port based multi tenancy](docs/port-based-multi-tenancy.md)
- [Troubleshoot](docs/troubleshoot.md)
# Custom app

32
development/README.md
View File

@ -251,38 +251,6 @@ frappe.db.connect()
The first command can take a few seconds to be executed, this is to be expected.
### 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;
```
## Manually start containers
In case you don't use VSCode, you may start the containers manually with the following command:

42
docs/add-custom-domain-using-traefik.md Normal file
View File

@ -0,0 +1,42 @@
Add following labels to *-nginx 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, use one of below
- "traefik.http.routers.custom-domain.tls.certresolver=myresolver" # For Single Bench
- "traefik.http.routers.custom-domain.tls.certresolver=le" # For Docker Swarm
```
Example:
```yaml
frontend:
image: frappe/erpnext-nginx:${ERPNEXT_VERSION}
restart: on-failure
environment:
- FRAPPE_PY=erpnext-python
- FRAPPE_PY_PORT=8000
- FRAPPE_SOCKETIO=frappe-socketio
- SOCKETIO_PORT=9000
labels:
- "traefik.enable=true"
- "traefik.http.routers.frontend.rule=Host(${SITES})"
- "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"
# Add following header only if TLS is needed in case of live server
- "traefik.http.routers.custom-domain.tls.certresolver=myresolver"
- "${ENTRYPOINT_LABEL}"
- "${CERT_RESOLVER_LABEL}"
- "traefik.http.services.frontend.loadbalancer.server.port=80"
volumes:
- sites-vol:/var/www/html/sites:rw
- assets-vol:/assets:rw
```
This will add `custom.localhost` as custom domain for `mysite.localhost`

121
docs/backup-and-push-cronjob.md Normal file
View File

@ -0,0 +1,121 @@
Install [crazy-max/swarm-cronjob](https://github.com/crazy-max/swarm-cronjob) and then deploy following stack.
```yaml
version: "3.7"
services:
backup:
image: frappe/erpnext-worker:version-13
entrypoint: ["bash", "-c"]
command: ["docker-entrypoint.sh backup; docker-entrypoint.sh push-backup"]
environment:
- WITH_FILES=1
- BUCKET_NAME=backups
- REGION=region
- ACCESS_KEY_ID=access_id_from_provider
- SECRET_ACCESS_KEY=secret_access_from_provider
- ENDPOINT_URL=https://region.storage-provider.com
- BUCKET_DIR=frappe-bench
volumes:
- "sites-vol:/home/frappe/frappe-bench/sites"
deploy:
labels:
- "swarm.cronjob.enable=true"
- "swarm.cronjob.schedule=0 */3 * * *"
- "swarm.cronjob.skip-running=true"
replicas: 0
restart_policy:
condition: none
networks:
- frappe-network
volumes:
sites-vol:
external: true
name: frappe-bench-v12_sites-vol
networks:
frappe-network:
external: true
```
Note:
- In Above stack, `backup` runs every 3 hours.
- Change image and tag version as per need.
- Change environment variables as per the bucket credentials.
- Change cron string(s) as per need.
### For docker-compose based installation not using docker swarm
Add minio
```yaml
version: "3.7"
services:
minio:
image: minio/minio
command: ["server", "/data"]
environment:
- MINIO_ACCESS_KEY=RANDOMACCESSKEY
- MINIO_SECRET_KEY=RANDOMSECRETKEY
volumes:
- "minio-vol:/data"
networks:
- erpnext-network
# Do not enable, check how to secure minio, out of scope of this project.
#labels:
# - "traefik.enable=true"
# - "traefik.http.routers.minio.rule=Host(`backup.example.com`)"
# - "traefik.http.routers.minio.entrypoints=websecure"
# - "traefik.http.routers.minio.tls.certresolver=myresolver"
# - "traefik.http.services.minio.loadbalancer.server.port=9000"
networks:
erpnext-network:
external: true
name: <your_frappe_docker_project_name>_default
volumes:
minio-vol:
```
Create backup service. Create file `backup-job.yml`
```yaml
version: "3.7"
services:
push-backup:
image: frappe/erpnext-worker:v13
entrypoint: ["bash", "-c"]
command: ["docker-entrypoint.sh backup; docker-entrypoint.sh push-backup"]
environment:
- WITH_FILES=1
- BUCKET_NAME=erpnext
- REGION=us-east-1
- ACCESS_KEY_ID=RANDOMACCESSKEY
- SECRET_ACCESS_KEY=RANDOMSECRETKEY
- ENDPOINT_URL=http://minio:9000
- BUCKET_DIR=backups
- BACKUP_LIMIT=8
volumes:
- "sites-vol:/home/frappe/frappe-bench/sites"
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
```
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
```

18
docs/bench-console-and-vscode-debugger.md Normal file
View File

@ -0,0 +1,18 @@
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
View 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 .
```

10
docs/connect-to-localhost-services-from-containers-for-local-app-development.md Normal file
View File

@ -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`.

10
docs/patch-code-from-images.md Normal file
View 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 install_app custom_app https://github.com/username/custom_app version-12
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
View 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`

55
docs/troubleshoot.md Normal file
View 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