# Setup Examples

This guide provides practical examples for common setup scenarios. These examples build upon the [container setup guide](01-overview.md) 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](../05-development/01-development.md).

## Prerequisites

- [docker](https://docker.com/get-started)
- [docker compose v2](https://docs.docker.com/compose/cli-command)
- Cloned `frappe_docker` repository

## Setup Environment Variables

Copy the example docker environment file to `.env`:

```sh
cp example.env .env
```

Edit `.env` and set variables according to your needs. See [environment variables](04-env-variables.md) 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:

```shell
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

```sh
# 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

```sh
# 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_RULE` environment variables
- DNS must point to your server IP

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

> **Note:** Ensure your `SITES_RULE` variable is properly formatted. See [environment variables](04-env-variables.md) for the correct format.

## Create First Site

After starting containers, create your first site. Refer to [site operations](../04-operations/01-site-operations.md#setup-new-site) for detailed instructions.

## Updating Images

To update to newer versions of Frappe or ERPNext:

```sh
# 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](../04-operations/01-site-operations.md#migrate-site).

---

**Back:** [Start Setup →](03-start-setup.md)

**Next:** [Single Server Example →](07-single-server-example.md)