docs: improve and organize docs (#791)

* docs: improve and organize docs

* docs: improve setup options

README.md

@@ -31,13 +31,12 @@ 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)
 - Examples:
   - [Single Server](docs/single-server-example.md)
-  - [Kubernetes (frappe/helm)](https://helm.erpnext.com),
+  - [Setup options](docs/setup-options.md)
-- [site operations](docs/site-operations.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)
@@ -48,7 +47,7 @@ Also, there's docs to help with deployment:
 
 # Custom app
 
-Learn how to containerize your custom Frappe app in [this guide](custom_app/README.md).
+Learn how to containerize your custom Frappe app(s) in [this guide](custom_app/README.md).
 
 # Contributing
 

docs/add-custom-domain-using-traefik.md

@@ -1,28 +0,0 @@
-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`

docs/backup-and-push-cronjob.md

@@ -8,7 +8,7 @@ services:
     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()))")
+      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 \

docs/connect-to-localhost-services-from-containers-for-local-app-development.md

@@ -1,10 +1,13 @@
-Not using separate container
 Add following to frappe container from the `.devcontainer/docker-compose.yml`:
 
 ```yaml
-extra_hosts:
+...
-  app1.localhost: 172.17.0.1
+  frappe:
-  app2.localhost: 172.17.0.1
+    ...
+    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`.

docs/patch-code-from-images.md

@@ -5,6 +5,30 @@ 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
+...
+USER root
 RUN sed -i -e "s/Your verification code is/আপনার লগইন কোড/g" /home/frappe/frappe-bench/apps/frappe/frappe/twofactor.py
+USER frappe
+...
+
+```
+
+Example for `nginx` image,
+
+```Dockerfile
+FROM frappe/erpnext-nginx:v13.27.0
+
+# Hack to use Frappe/ERPNext offline.
+RUN sed -i 's/navigator.onLine/navigator.onLine||true/' \
+  /usr/share/nginx/html/assets/js/desk.min.js \
+  /usr/share/nginx/html/assets/js/dialog.min.js \
+  /usr/share/nginx/html/assets/js/frappe-web.min.js
+```
+
+Alternatively copy the modified source code file directly over `/home/frappe/frappe-bench/apps/frappe/frappe/twofactor.py`
+
+```Dockerfile
+...
+COPY twofactor.py /home/frappe/frappe-bench/apps/frappe/frappe/twofactor.py
+...
 ```

docs/setup-options.md

@@ -4,6 +4,11 @@ Make sure you've cloned this repository and switch to the directory before execu
 
 Commands will generate YAML as per the environment for setup.
 
+## Prerequisites
+
+- [docker](https://docker.com/get-started)
+- [docker compose v2](https://docs.docker.com/compose/cli-command)
+
 ## Setup Environment Variables
 
 Copy the example docker environment file to `.env`:
@@ -16,48 +21,71 @@ Note: To know more about environment variable [read here](./images-and-compose-f
 
 ## Generate docker-compose.yml for variety of setups
 
+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)
+
+### Store the yaml files
+
+YAML files generated by `docker compose config` command can be stored in a directory. We will create a directory called `gitops` in the user's home.
+
+```shell
+mkdir ~/gitops
+```
+
+You can make the directory into a private git repo which stores the yaml and secrets. It can help in tracking changes.
+
+Instead of `docker compose config`, you can directly use `docker compose up` to start the containers and skip storing the yamls in `gitops` directory.
+
 ### Setup Frappe without proxy and external MariaDB and Redis
 
+In this case make sure you've set `DB_HOST`, `DB_PORT`, `REDIS_CACHE`, `REDIS_QUEUE` and `REDIS_SOCKETIO`
+environment variables or the `configurator` will fail.
+
 ```sh
 # Generate YAML
-docker-compose -f compose.yaml -f overrides/compose.noproxy.yaml config > ~/gitops/docker-compose.yml
+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
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
 ```
 
 ### Setup ERPNext with proxy and external MariaDB and Redis
 
+In this case make sure you've set `DB_HOST`, `DB_PORT`, `REDIS_CACHE`, `REDIS_QUEUE` and `REDIS_SOCKETIO`
+environment variables or the `configurator` will fail.
+
 ```sh
 # Generate YAML
-docker-compose -f compose.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
+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 \
+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
+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 \
+docker compose -f compose.yaml \
   -f overrides/compose.erpnext.yaml \
   -f overrides/compose.mariadb.yaml \
   -f overrides/compose.redis.yaml \
@@ -65,13 +93,12 @@ docker-compose -f compose.yaml \
   config > ~/gitops/docker-compose.yml
 
 # Start containers
-docker-compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
 ```
 
-Notes:
+## Create first site
 
-- Make sure to replace `<project-name>` with the desired name you wish to set for the project.
+After starting containers, the first site needs to be created. Refer [site operations](./site-operations.md#setup-new-site).
-- This setup is not to be used for development. A complete development environment is available [here](../development)
 
 ## Updating Images
 
@@ -82,15 +109,21 @@ Switch to the root of the `frappe_docker` directory before running the following
 nano .env
 
 # Pull new images
-docker-compose -f compose.yaml \
+docker compose -f compose.yaml \
   -f overrides/compose.erpnext.yaml \
   # ... your other overrides
   config > ~/gitops/docker-compose.yml
 
-docker-compose --project-name <project-name> -f ~/gitops/docker-compose.yml pull
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml pull
+
+# Stop containers
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml down
+
+# Remove assets volume for repopulation
+docker volume rm <name of assets volume>
 
 # Restart containers
-docker-compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
 ```
 
 To migrate sites refer [site operations](./site-operations.md#migrate-site)

docs/troubleshoot.md

@@ -35,6 +35,8 @@ GRANT ALL PRIVILEGES ON `db_name`.* TO 'db_name'@'%'; FLUSH PRIVILEGES;
 EXIT;
 ```
 
+Note: For MariaDB 10.4 and above use `mysql.global_priv` instead of `mysql.user`.
+
 ### Letsencrypt companion not working
 
 - Nginx Letsencrypt Companion needs to be setup before starting ERPNext services.

overrides/compose.https.yaml

@@ -5,6 +5,7 @@ services:
       - traefik.http.services.frontend.loadbalancer.server.port=8080
       - traefik.http.routers.frontend-http.entrypoints=websecure
       - traefik.http.routers.frontend-http.tls.certresolver=main-resolver
+      - traefik.http.routers.frontend-http.rule=HostRegexp(`{any:.+}`)
 
   proxy:
     image: traefik:2.5