From f41abc97afa35c5126693b797ff7ecb18ff6006c Mon Sep 17 00:00:00 2001 From: Daniel Radl Date: Tue, 23 Dec 2025 12:41:22 +0100 Subject: [PATCH] docs: added deployment methode chooser --- .../01-choosing-a-deployment-method.md | 122 ++++++++++++++++++ .../02-docker-immutability.md | 48 +++++++ ...nux-mac.md => 03-quick-start-linux-mac.md} | 0 ...se-setup.md => 04-single-compose-setup.md} | 0 docs/getting-started.md | 4 + 5 files changed, 174 insertions(+) create mode 100644 docs/01-getting-started/01-choosing-a-deployment-method.md create mode 100644 docs/01-getting-started/02-docker-immutability.md rename docs/01-getting-started/{01-quick-start-linux-mac.md => 03-quick-start-linux-mac.md} (100%) rename docs/01-getting-started/{02-single-compose-setup.md => 04-single-compose-setup.md} (100%) diff --git a/docs/01-getting-started/01-choosing-a-deployment-method.md b/docs/01-getting-started/01-choosing-a-deployment-method.md new file mode 100644 index 00000000..11b39a8f --- /dev/null +++ b/docs/01-getting-started/01-choosing-a-deployment-method.md @@ -0,0 +1,122 @@ +# Choosing a Deployment or Development Method + +This repository (`frappe_docker`) supports **multiple ways to run Frappe using Docker**. +Each method is designed for a **specific purpose**, and they are **not interchangeable**. + +This document explains: + +- All supported ways to use this repository +- Which method to choose depending on your goal +- Common misconceptions, especially around persistence and app installation + +Reading this document **before following any setup guide** is strongly recommended. + +## Overview + +| Goal | Recommended Method | Production Ready | +| ---------------------------- | ------------------------- | ---------------- | +| Quick exploration | `pwd.yml` | ❌ | +| Local development | VS Code Devcontainers | ❌ | +| Automated production install | Easy Install Script | ✅ | +| Manual production deployment | `compose.yml` + overrides | ✅ | + +## 1. `pwd.yml` – Quick Test / Exploration Setup + +The `pwd.yml` file is a **single, self-contained Docker Compose file** intended for: + +- Trying out Frappe and ERPNext +- Demos and short-lived test environments +- Learning the basics without setup overhead + +### Characteristics + +- One Compose file +- Minimal configuration +- Fast startup +- Disposable by design + +### Limitations + +- ❌ **Not intended for production** +- ❌ **Not intended for development** +- ❌ **Not suitable as a migration starting point** + +If you start with `pwd.yml`, you should expect to **throw the environment away**. + +## 2. VS Code Devcontainers – Local Development Setup + +The development setup described in [`/docs/05-development`](../05-development) + +uses **VS Code Devcontainers** to provide a **local Frappe development environment**. + +### Intended Use + +- Developing Frappe or custom apps +- Working with source code +- Debugging and testing changes locally + +### Key Differences from Other Setups + +- Optimized for **interactive development** +- Code is editable live +- Containers are tailored for developer workflows +- Not designed to represent a production environment + +### Important Notes + +- ❌ **Not a deployment method** +- ❌ **Not intended for production** +- ✔ The **correct way** to do local development with this repository + +Using production-oriented setups (`pwd.yml` or `compose.yml`) for development is strongly discouraged. + +## 3. Easy Install Script (from `frappe/bench`) + +The Easy Install script provided in the [`frappe/bench`](https://github.com/frappe/bench) repository uses `frappe_docker` internally and automates a full deployment process. + +It is comparable to what a **deployment pipeline** would perform. + +### What It Does + +- Installs Docker and prerequisites +- Pulls and configures `frappe_docker` +- Uses production-grade images and services +- Reduces manual configuration + +### Intended Use + +- Production environments +- Users who want a guided, automated installation +- Server deployments with minimal manual steps + +### Production Readiness + +✔ **Yes** — suitable for real production systems +✔ Uses the same components as the manual production setup + +## 4. `compose.yml` + Overrides – Intended Production Setup + +This is the **canonical production deployment method** for `frappe_docker`. + +It uses: + +- The main `compose.yml` +- Override files from the `overrides/` directory + +Detailed instructions are available in [`/docs/02-setup`](../02-setup) + +### Characteristics + +- Explicit service definitions +- Flexible and configurable +- Designed for long-running production environments +- Suitable for advanced and customized deployments + +**This is the preferred approach for teams managing their own infrastructure.** + +## Summary + +- Each setup serves a **distinct purpose** +- Development, testing, and production are **separate workflows** +- Do not expect to evolve a disposable setup into production +- Apps must be included **at build time**, not installed later ([Docker immutability](02-docker-immutability.md)) diff --git a/docs/01-getting-started/02-docker-immutability.md b/docs/01-getting-started/02-docker-immutability.md new file mode 100644 index 00000000..38a82330 --- /dev/null +++ b/docs/01-getting-started/02-docker-immutability.md @@ -0,0 +1,48 @@ +# Important Concept: Immutability and Persistence + +A frequent source of confusion is how **Docker-based Frappe deployments handle persistence**. + +### Containers Are Immutable + +Docker containers are **not meant to be modified after they are built**. +You should only change: + +- Environment variables +- Mounted volumes +- The Docker image itself (via rebuild) + +### What Is Persistent + +Typically, only these paths are persisted: + +- Site data (`/sites`) +- Database storage + +This allows you to: + +- Create new sites +- Run migrations +- Perform backups and restores +- Recreate containers safely + +## Installing Apps After Deployment + +### ❌ Not Supported + +Installing apps into a running container is **not supported**. + +`bench get-app` is an examples of an common but unsupported action. + +### Why? + +- Apps are part of the **Docker image** +- Runtime changes are lost on container recreation +- This ensures reproducibility and stability + +### Correct Workflow + +1. Add the app to the image build configuration +2. Rebuild the Docker image +3. Redeploy the stack + +This applies to **all production-oriented setups**. diff --git a/docs/01-getting-started/01-quick-start-linux-mac.md b/docs/01-getting-started/03-quick-start-linux-mac.md similarity index 100% rename from docs/01-getting-started/01-quick-start-linux-mac.md rename to docs/01-getting-started/03-quick-start-linux-mac.md diff --git a/docs/01-getting-started/02-single-compose-setup.md b/docs/01-getting-started/04-single-compose-setup.md similarity index 100% rename from docs/01-getting-started/02-single-compose-setup.md rename to docs/01-getting-started/04-single-compose-setup.md diff --git a/docs/getting-started.md b/docs/getting-started.md index ea615c37..f87b8617 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -66,6 +66,10 @@ Real-time: ### 📁 Core Configuration Files +> ⚠️ Before deploying, read +> **[Choosing a Deployment Method](01-getting-started/01-choosing-a-deployment-method.md)** +> to understand the differences between `pwd.yml`, development setup, the Easy Install script and the production setup. + - **compose.yaml** - Main Docker Compose file defining all services - **example.env** - Environment variables template (copy to `.env`) - **pwd.yml** - "Play with Docker" - simplified single-file setup for quick testing