frappe_docker/docs/02-setup/06-setup-examples.md

Setup Examples

This guide provides practical examples for common setup scenarios. These examples build upon the container setup guide and demonstrate how to combine the base compose file with overrides.

Note: This setup is not for development. A complete development environment is available here.

Prerequisites

• docker
• docker compose v2
• Cloned frappe_docker repository

Setup Environment Variables

Copy the example docker environment file to .env:

cp example.env .env

Edit .env and set variables according to your needs. See environment variables for detailed descriptions of all available variables.

Storing Generated YAML Files

YAML files generated by docker compose config can be stored in a directory for version control and management:

mkdir ~/gitops

You can make this directory into a private git repository to track changes to your configuration. This is especially useful for managing multiple environments or projects.

Alternatively, you can directly use docker compose up to start containers without storing intermediate YAML files.

Example 1: Frappe without Proxy (Direct Access)

Setup Frappe with containerized MariaDB and Redis, exposing the application directly on port :8080 without a reverse proxy.

Requirements:

• Set DB_PASSWORD in .env (or use default 123)
• No external database or Redis needed

# Generate YAML
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

# Start containers
docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d

Example 2: ERPNext with External Database and Redis

Setup ERPNext using external MariaDB and Redis instances with Traefik HTTP proxy.

Requirements:

• Set DB_HOST, DB_PORT, REDIS_CACHE, and REDIS_QUEUE in .env
• External database and Redis must be accessible

# Generate YAML
docker compose -f compose.yaml \
  -f overrides/compose.proxy.yaml \
  config > ~/gitops/docker-compose.yml

# Start containers
docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d

Example 3: Production Setup with HTTPS

Setup Frappe/ERPNext using containerized MariaDB and Redis with Let's Encrypt SSL certificates via Traefik.

Requirements:

• Set LETSENCRYPT_EMAIL and SITES environment variables
• DNS must point to your server IP

# 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

Note: Ensure your SITES variable is properly formatted. See environment variables for the correct format.

Create First Site

After starting containers, create your first site. Refer to site operations for detailed instructions.

Updating Images

To update to newer versions of Frappe or ERPNext:

# 1. Update environment variables in .env
nano .env
# Edit ERPNEXT_VERSION and FRAPPE_VERSION as needed

# 2. Regenerate compose file with new versions
docker compose --env-file .env \
  -f compose.yaml \
  # ... your other overrides
  config > ~/gitops/docker-compose.yml

# 3. Pull new images
docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml pull

# 4. Stop containers
docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml down

# 5. Restart containers
docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d

Note:

• Pull and stop container commands can be skipped if immutable image tags are used
• docker compose up -d will pull new immutable tags if not found

To migrate sites after updating, refer to site operations.

---

Back: Start Setup →

Next: Single Server Example →