diff --git a/docs/03-production/01-tls-ssl-setup.md b/docs/03-production/01-tls-ssl-setup.md index 07a0787b..b88fc8c1 100644 --- a/docs/03-production/01-tls-ssl-setup.md +++ b/docs/03-production/01-tls-ssl-setup.md @@ -1,25 +1,53 @@ -# Accessing ERPNext through https on local deployment +# TLS/SSL Setup Overview -- ERPNext container deployment can be accessed through https easily using Caddy web server, Caddy will be used as reverse proxy and forward traffics to the frontend container. +Frappe Docker supports multiple TLS/SSL approaches. Choose the one that matches your routing needs and where you want the proxy to run. -### Prerequisites +## Options -- Caddy -- Adding a domain name to hosts file +### Traefik (built-in HTTPS) -#### Installation of caddy webserver +- Use `overrides/compose.https.yaml` +- Best for multi-site setups and advanced routing rules +- Requires `SITES_RULE` and `LETSENCRYPT_EMAIL` +- See [Environment Variables](../02-setup/04-env-variables.md) and [Setup Examples](../02-setup/06-setup-examples.md#example-3-production-setup-with-https) -- Follow the official Caddy website for the installation guide https://caddyserver.com/docs/install - After completing the installation open the configuration file of Caddy ( You find the config file in ` /etc/caddy/Caddyfile`), add the following configuration to forward traffics to the ERPNext frontend container +#### Traefik deployment models -```js -erp.localdev.net { - tls internal +- **Single stack (Traefik inside the stack):** + - Use `compose.proxy.yaml` (HTTP) or `compose.https.yaml` (HTTPS) + - Traefik runs as `proxy` in the same stack +- **Central Traefik for multiple stacks:** + - Run a dedicated Traefik stack with `compose.traefik.yaml` (and optional `compose.traefik-ssl.yaml` for the dashboard) + - Each Frappe stack uses `compose.multi-bench.yaml` (and optional `compose.multi-bench-ssl.yaml`) + - This connects stacks to the shared `traefik-public` network - reverse_proxy localhost:8085 { +### nginx-proxy + acme-companion - } -} -``` +- Use `overrides/compose.nginxproxy.yaml` plus `overrides/compose.nginxproxy-ssl.yaml` +- Simple host-based routing for single-bench or small setups +- Requires `NGINX_PROXY_HOSTS` and `LETSENCRYPT_EMAIL` +- See [nginx-proxy + acme-companion](04-nginx-proxy-acme-companion.md) -- Caddy's root certificate must be added to other computers if computers from different networks access the ERPNext through https. +## Traefik vs nginx-proxy + acme-companion + +| Topic | Traefik (compose.https.yaml) | nginx-proxy + acme-companion | +| ------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ | +| Configuration | Labels with `SITES_RULE` expression | Environment variables (`NGINX_PROXY_HOSTS`) | +| Routing | Flexible (rules, headers, paths) | Host-based only | +| Multi-site | Strong | Works for simple host lists | +| TLS/ACME | Built-in | Separate companion container | +| Certificate storage | `cert-data` volume (`/letsencrypt/acme.json`) | `nginx-proxy-certs` + `acme-data` volumes (`/etc/nginx/certs`, `/etc/acme.sh`) | +| Complexity | Moderate | Low | +| Observability | Optional dashboard (not enabled here) | No built-in dashboard | + +### Caddy (external reverse proxy) + +- Run Caddy on the host and proxy to the frontend container +- Useful for local HTTPS or when you already use Caddy +- See [Caddy reverse proxy](05-caddy-https.md) + +## Common requirements + +- DNS must point to the server for public TLS certificates +- Ports 80 and 443 must be reachable for HTTP-01 challenges +- Use `HTTP_PUBLISH_PORT` and `HTTPS_PUBLISH_PORT` if you need non-default ports diff --git a/docs/03-production/05-caddy-https.md b/docs/03-production/05-caddy-https.md new file mode 100644 index 00000000..a8683c5d --- /dev/null +++ b/docs/03-production/05-caddy-https.md @@ -0,0 +1,44 @@ +# Caddy reverse proxy (local HTTPS) + +This guide shows how to use Caddy as an external reverse proxy in front of the frontend container. It is most useful for local HTTPS or internal networks. + +## Prerequisites + +- Expose the frontend container on a host port (default 8080) +- Add a local domain to your hosts file (or use internal DNS) +- Install Caddy + +## Step 1: Expose the frontend service + +Include the no-proxy override so the frontend is reachable on the host: + +```sh +docker compose -f compose.yaml \ + -f overrides/compose.mariadb.yaml \ + -f overrides/compose.redis.yaml \ + -f overrides/compose.noproxy.yaml \ + config > ~/gitops/docker-compose.yml + +docker compose --project-name -f ~/gitops/docker-compose.yml up -d +``` + +If you changed the HTTP port, note the value of `HTTP_PUBLISH_PORT` for the next step. + +## Step 2: Configure Caddy + +Add a site block to your Caddyfile (usually `/etc/caddy/Caddyfile`): + +```caddy +erp.localdev.net { + tls internal + reverse_proxy localhost:8080 +} +``` + +Replace `8080` with your published frontend port if you changed it. + +## Step 3: Trust the Caddy root certificate + +When using `tls internal`, Caddy issues certificates from its internal CA. Import and trust the Caddy root certificate on any client that needs to access the site. + +See also: [TLS/SSL Setup Overview](01-tls-ssl-setup.md).