mirror of
https://github.com/frappe/frappe_docker.git
synced 2026-06-17 21:55:09 +00:00
09934d576c
* docs: reorganize documentation structure into logical categories Restructure documentation into organized directories for better navigation: - getting-started/: Quick start guides for new users - setup/: Setup and configuration guides - production/: Production deployment guides (backup, TLS, multi-tenancy) - operations/: Site operations and management - development/: Development workflow guides - migration/: Migration guides - troubleshooting/: Troubleshooting guides - reference/: Reference documentation (container setup, build configs) Rename files for consistency: - Use kebab-case naming convention throughout - Remove numbered prefixes from container-setup files - Use descriptive names (backup-strategy, tls-ssl-setup, etc.) Update all internal cross-references to reflect new file locations. Update README.md with organized documentation structure. Fix image paths in development.md to use correct relative paths. * docs: add numeric prefixes to directories and files for navigation order Add numeric prefixes (01-08) to documentation directories to indicate reading order and flow for first-time users: - 01-getting-started: Quick start guides - 02-setup: Setup and configuration - 03-production: Production deployment - 04-operations: Site operations - 05-development: Development guides - 06-migration: Migration guides - 07-troubleshooting: Troubleshooting - 08-reference: Reference documentation Add numeric prefixes to files within directories to guide readers through documentation in a logical sequence. Update all cross-references throughout documentation to use new numbered paths. Update README.md to reflect the new structure. * docs: move container-setup to 02-setup and integrate setup-options content Move container-setup directory from 08-reference/ to 02-setup/ to follow PR feedback. The container-setup documentation provides a more linear and coherent flow compared to the previous unstructured setup files. Changes: - Move container-setup/ from docs/08-reference/ to docs/02-setup/ - Integrate content from setup-options.md into structured flow: - Create new 06-setup-examples.md with practical deployment scenarios - Enhance 03-start-setup.md with site creation details from setup-options - Remove redundant 01-setup-options.md (content now integrated) - Rename 02-single-server-example.md to 07-single-server-example.md - Update all cross-references throughout documentation: - Update README.md with new structure under Setup section - Fix links in site-operations.md and migration docs - Add navigation links between container-setup files and examples - Maintain container-setup's linear flow: overview → build → start → env → overrides - Add practical examples document (06-setup-examples.md) that follows the container-setup guide Result: Documentation now follows a clear progression from conceptual overview through practical examples, with all setup information properly organized under 02-setup/. * docs: remove container-setup subfolder and flatten structure Move all files from docs/02-setup/container-setup/ directly into docs/02-setup/ to eliminate unnecessary subfolder. Files are already numbered sequentially, so they work perfectly at the same level. Changes: - Move all files from container-setup/ subfolder to 02-setup/ root - Remove container-setup/ subfolder - Update all cross-references: - Update README.md paths (remove container-setup/ from all links) - Fix references in site-operations.md - Fix references in migration docs - Update internal references in 06-setup-examples.md - Fix relative path references in 01-overview.md, 02-build-setup.md, 03-start-setup.md Result: Cleaner, flatter structure with all numbered setup files at the same level, making navigation more straightforward. * fix: Pre-commit failure is fixed --------- Co-authored-by: adithya <adithya.a@bayesian.in>
138 lines
4.3 KiB
Markdown
138 lines
4.3 KiB
Markdown
# 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` 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` 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)
|