From 2926e183bc900412909e2cb503045843d69c6479 Mon Sep 17 00:00:00 2001 From: duthink Date: Thu, 23 Oct 2025 22:23:54 +0530 Subject: [PATCH] docs: refactor guide to be general-purpose with prominent placement - Rename django-dev-transition-guide.md to getting-started-guide.md - Update README.md to feature guide prominently in Getting Started section - Make guide framework-agnostic while keeping Django comparisons optional The guide now serves developers from all backgrounds, with Django comparisons included as an optional reference section at the end. --- README.md | 4 + docs/getting-started-guide.md | 903 ++++++++++++++++++++++++++-------- 2 files changed, 696 insertions(+), 211 deletions(-) diff --git a/README.md b/README.md index da11161a..45e2dfb3 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ Everything about [Frappe](https://github.com/frappe/frappe) and [ERPNext](https: # Getting Started +**New to Frappe Docker?** Read the [Getting Started Guide](docs/getting-started-guide.md) for a comprehensive overview of repository structure, development workflow, custom apps, Docker concepts, and quick start examples. + To get started you need [Docker](https://docs.docker.com/get-docker/), [docker-compose](https://docs.docker.com/compose/), and [git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git) setup on your machine. For Docker basics and best practices refer to Docker's [documentation](http://docs.docker.com). Once completed, chose one of the following two sections for next steps. @@ -49,6 +51,8 @@ If you ran in a Dev Docker environment, to view container logs: `docker compose # Documentation +### [Getting Started Guide](docs/getting-started-guide.md) + ### [Frequently Asked Questions](https://github.com/frappe/frappe_docker/wiki/Frequently-Asked-Questions) ### [Production](#production) diff --git a/docs/getting-started-guide.md b/docs/getting-started-guide.md index 154b90ae..84d418ed 100644 --- a/docs/getting-started-guide.md +++ b/docs/getting-started-guide.md @@ -1,10 +1,9 @@ -# Frappe Docker Development Guide for Django Developers +# Getting Started with Frappe Docker -*A comprehensive guide for Django developers getting started with Frappe Docker* +*A comprehensive guide for developers getting started with Frappe Docker, with comparisons to Django for developers familiar with that framework* ## Table of Contents - [Understanding Frappe Docker Architecture](#understanding-frappe-docker-architecture) -- [Frappe vs Django Concepts](#frappe-vs-django-concepts) - [Repository Structure](#repository-structure) - [Custom Apps Explained](#custom-apps-explained) - [Development Workflow](#development-workflow) @@ -12,168 +11,220 @@ - [Docker Concepts: Bind Mounts](#docker-concepts-bind-mounts) - [Fork Management Best Practices](#fork-management-best-practices) - [Quick Start Examples](#quick-start-examples) +- [Framework Comparisons](#framework-comparisons) + - [Frappe vs Django](#frappe-vs-django-concepts) +- [Resources and References](#resources-and-references) --- ## Understanding Frappe Docker Architecture -Frappe Docker provides a comprehensive containerized environment for developing and deploying Frappe/ERPNext applications. Unlike typical Django setups, Frappe uses a **multi-service architecture**. +Frappe Docker provides a comprehensive containerized environment for developing and deploying Frappe/ERPNext applications. It uses a **multi-service architecture** that handles everything from web serving to background job processing. ### Core Services -- **backend** - Gunicorn server (like your Django app server) -- **frontend** - Nginx static file server + reverse proxy -- **queue-short/long** - Background job workers (like Celery) -- **scheduler** - Cron-like task scheduler -- **websocket** - Real-time Socket.IO server -- **db** - MariaDB/PostgreSQL database -- **redis-cache/queue** - Caching and job queues +- **backend** - Gunicorn WSGI server running Frappe applications +- **frontend** - Nginx for static files and reverse proxy +- **queue-short/long** - Background job workers for asynchronous task processing +- **scheduler** - Cron-style task scheduler for periodic jobs +- **websocket** - Socket.IO server for real-time communications +- **db** - MariaDB/PostgreSQL database server +- **redis-cache/queue** - Redis for caching and job queue management -## Frappe vs Django Concepts +### How Services Work Together -### Project Structure Comparison - -**Django Project:** -```python -myproject/ -├── myproject/ # Project settings -├── blog/ # Django app -├── shop/ # Django app -└── users/ # Django app ``` +User Request + ↓ +[frontend (Nginx)] → Static files served directly + ↓ +[backend (Gunicorn)] → Dynamic content processing + ↓ ↓ +[db (MariaDB)] [redis-cache] + +Background Tasks: +[scheduler] → [redis-queue] → [queue-short/long workers] -**Frappe Bench:** +Real-time: +[websocket (Socket.IO)] ←→ [redis-cache] ``` -bench/ -├── apps/ -│ ├── frappe/ # Core framework (like Django itself) -│ ├── erpnext/ # Business app (complete ERP solution) -│ ├── hrms/ # HR Management app -│ └── my_custom_app/ # YOUR custom app -└── sites/ - └── mysite.com/ # Site using the apps above -``` - -### Key Differences from Django - -1. **Multi-tenancy**: One installation can serve multiple sites -2. **Built-in job queues**: No need for separate Celery setup -3. **Real-time features**: WebSocket support built-in -4. **Bench management**: Tool for managing multiple apps/sites -5. **Database per site**: Each site gets its own database ## Repository Structure ### 📁 Core Configuration Files - **compose.yaml** - Main Docker Compose file defining all services -- **example.env** - Environment variables template +- **example.env** - Environment variables template (copy to `.env`) - **pwd.yml** - "Play with Docker" - simplified single-file setup for quick testing -- **docker-bake.hcl** - Advanced Docker Buildx configuration +- **docker-bake.hcl** - Advanced Docker Buildx configuration for multi-architecture builds ### 📁 images/ - Docker Image Definitions -- **images/bench/** - Development container with full Frappe tooling -- **images/production/** - Production-ready containers -- **images/custom/** - Build custom apps using apps.json -- **images/layered/** - Optimized layered builds +- **images/bench/** - Development container with full Frappe tooling and CLI +- **images/production/** - Production-optimized containers (smaller, security-hardened) +- **images/custom/** - Build custom apps using apps.json configuration +- **images/layered/** - Optimized layered builds for faster rebuilds ### 📁 overrides/ - Compose File Extensions -Docker Compose "overrides" that extend the base compose.yaml: -- **compose.mariadb.yaml** - Adds MariaDB service -- **compose.redis.yaml** - Adds Redis service -- **compose.proxy.yaml** - Adds Traefik reverse proxy -- **compose.https.yaml** - Adds SSL/TLS support +Docker Compose "overrides" that extend the base compose.yaml for different scenarios: +- **compose.mariadb.yaml** - Adds MariaDB database service +- **compose.redis.yaml** - Adds Redis caching service +- **compose.proxy.yaml** - Adds Traefik reverse proxy for multi-site hosting +- **compose.https.yaml** - Adds SSL/TLS certificate management ### 📁 development/ - Dev Environment -- **development/installer.py** - Automated bench/site creation script -- Contains your local development files (git-ignored) +- **development/installer.py** - Automated bench/site creation and configuration script +- Contains your local development files (git-ignored to prevent accidental commits) ### 📁 resources/ - Runtime Templates -- **nginx-entrypoint.sh** - Dynamic configuration generator script +- **nginx-entrypoint.sh** - Dynamic Nginx configuration generator script - **nginx-template.conf** - Nginx configuration template with variable substitution ## Custom Apps Explained ### What Are Frappe Custom Apps? -Custom apps are self-contained business applications that extend Frappe's functionality. Unlike Django apps that you build piece by piece, Frappe apps are complete business solutions. +Custom apps are self-contained, modular business applications that extend Frappe's functionality. They follow a convention-over-configuration approach where the framework provides most boilerplate automatically. ### Custom App Structure ``` my_custom_app/ -├── hooks.py # App configuration (like Django's apps.py) -├── modules.txt # List of modules in this app +├── hooks.py # App configuration and hooks into Frappe lifecycle +├── modules.txt # List of business modules in this app ├── my_custom_app/ │ ├── __init__.py │ ├── config/ -│ │ └── desktop.py # Desktop icons/shortcuts -│ ├── my_module/ # Business module -│ │ ├── doctype/ # Models (like Django models) +│ │ └── desktop.py # Desktop workspace icons and shortcuts +│ ├── my_module/ # Business domain module (e.g., sales, inventory) +│ │ ├── doctype/ # Document Types (data models) │ │ │ ├── customer/ -│ │ │ │ ├── customer.py # Python controller -│ │ │ │ ├── customer.json # Model definition -│ │ │ │ └── customer.js # Frontend logic -│ │ └── page/ # Custom pages -│ ├── public/ # Static files -│ ├── templates/ # Jinja2 templates -│ └── www/ # Web pages -└── requirements.txt # Python dependencies +│ │ │ │ ├── customer.py # Python controller (business logic) +│ │ │ │ ├── customer.json # Model definition (schema, validation) +│ │ │ │ └── customer.js # Frontend logic (UI interactions) +│ │ └── page/ # Custom pages (dashboards, reports) +│ ├── public/ # Static assets (CSS, JS, images) +│ ├── templates/ # Jinja2 templates for web pages +│ └── www/ # Web pages accessible via routes +└── requirements.txt # Python package dependencies ``` ### Built-in Features (Auto-generated) -Every Frappe app automatically gets: -- **REST API** (automatic from DocType definitions) -- **Permissions system** (row-level security built-in) -- **Audit trails** (automatic change tracking) -- **Custom fields** (users can add fields without code changes) -- **Workflows** (approval processes) -- **Reports** (built-in report builder) +Every Frappe app automatically includes: +- **REST API** - Automatic CRUD endpoints from DocType definitions +- **Permissions system** - Row-level and field-level access control +- **Audit trails** - Automatic version tracking and change history +- **Custom fields** - Runtime field additions without code changes +- **Workflows** - Configurable approval and state management +- **Reports** - Query builder and report designer +- **Print formats** - PDF generation with custom templates +- **Email integration** - Template-based email sending +- **File attachments** - Document attachment management ### Creating Custom Apps ```bash # Enter the development container docker exec -it bash -# Create new app +# Create new app (interactive prompts will ask for details) bench new-app my_custom_app # Install app to a site bench --site mysite.com install-app my_custom_app + +# Create a new DocType (data model) +bench --site mysite.com console +>>> bench.new_doc("DocType", {...}) +# Or use the web UI: Setup → Customize → DocType → New ``` ## Development Workflow ### Quick Test Setup (pwd.yml) +Perfect for evaluating Frappe Docker without any local setup: + ```bash git clone https://github.com/frappe/frappe_docker cd frappe_docker docker compose -f pwd.yml up -d -# Visit http://localhost:8080 (user: Administrator, pass: admin) + +# Monitor site creation (takes ~5 minutes) +docker compose -f pwd.yml logs -f create-site + +# Access once "create-site" container exits successfully +# Visit http://localhost:8080 +# Login: Administrator / admin ``` ### Full Development Setup -1. Copy devcontainer example: `cp -R devcontainer-example .devcontainer` -2. Use VSCode Dev Containers extension -3. Run installer: `cd /workspace/development && python installer.py` -4. Your development files appear in `development/frappe-bench/` +For active development with hot-reload and debugging: + +1. **Copy devcontainer configuration:** + ```bash + cp -R devcontainer-example .devcontainer + ``` + +2. **Open in VSCode with Dev Containers extension** (Remote - Containers) + - VSCode will detect `.devcontainer` and prompt to reopen in container + +3. **Run automated installer:** + ```bash + cd /workspace/development + python installer.py + # Follow interactive prompts for site name, apps to install, etc. + ``` + +4. **Access development files:** + ``` + development/frappe-bench/ # Your live development environment + ``` ### Development File Locations ``` development/ ├── frappe-bench/ # Your actual Frappe installation -│ ├── apps/ # Frappe apps (frappe, erpnext, custom apps) -│ │ ├── frappe/ # Core framework -│ │ ├── erpnext/ # ERPNext application -│ │ └── my_custom_app/ # Your custom apps -│ ├── sites/ # Your sites -│ │ ├── development.localhost/ # Main dev site -│ │ └── common_site_config.json # Shared config -│ └── env/ # Python virtual environment -└── .vscode/ # VSCode settings +│ ├── apps/ # All installed Frappe applications +│ │ ├── frappe/ # Core framework (don't modify directly) +│ │ ├── erpnext/ # ERPNext application (if installed) +│ │ └── my_custom_app/ # Your custom apps (edit freely) +│ ├── sites/ # Multi-tenant sites +│ │ ├── development.localhost/ # Default dev site +│ │ │ ├── site_config.json # Site-specific config +│ │ │ └── private/files/ # Uploaded files +│ │ └── common_site_config.json # Shared configuration +│ ├── env/ # Python virtual environment +│ ├── logs/ # Application logs +│ └── config/ # Bench-level configuration +└── .vscode/ # VSCode workspace settings +``` + +### Common Development Commands +```bash +# Inside container +bench start # Start development server with hot-reload + +# Database operations +bench migrate # Run database migrations +bench --site mysite.com migrate # Site-specific migration + +# Frontend builds +bench build # Build all app assets +bench build --app my_custom_app # Build specific app + +# Code generation +bench new-app # Create new app +bench new-site # Create new site + +# App management +bench get-app # Download app from git +bench install-app # Install app to current site +bench uninstall-app # Remove app from site + +# Debugging +bench console # Python REPL with Frappe context +bench mariadb # Database console ``` ## File Locations and Access ### Accessing Container Files ```bash -# Enter backend container +# Enter backend container shell docker compose -f pwd.yml exec backend bash # Navigate to bench directory @@ -182,112 +233,172 @@ cd /home/frappe/frappe-bench/ # Key directories: /home/frappe/frappe-bench/apps/ # All Frappe apps /home/frappe/frappe-bench/sites/ # Site data and configuration +/home/frappe/frappe-bench/logs/ # Application logs +/home/frappe/frappe-bench/env/ # Python virtual environment ``` ### Copying Files from Containers ```bash -# Copy files from container to host -docker compose -f pwd.yml cp backend:/home/frappe/frappe-bench/apps/ ./local-apps/ +# Copy entire app from container to host +docker compose -f pwd.yml cp backend:/home/frappe/frappe-bench/apps/my_app ./local-apps/ + +# Copy logs +docker compose -f pwd.yml cp backend:/home/frappe/frappe-bench/logs/ ./debug-logs/ + +# Copy site files +docker compose -f pwd.yml cp backend:/home/frappe/frappe-bench/sites/mysite.com ./backup/ ``` ### Useful Container Commands ```bash -# List sites +# List all sites docker compose -f pwd.yml exec backend bench list-sites -# List installed apps -docker compose -f pwd.yml exec backend bench list-apps +# List installed apps for a site +docker compose -f pwd.yml exec backend bench --site mysite.com list-apps # View site configuration docker compose -f pwd.yml exec backend cat /home/frappe/frappe-bench/sites/common_site_config.json + +# Check logs in real-time +docker compose -f pwd.yml logs -f backend + +# Execute bench command +docker compose -f pwd.yml exec backend bench --site mysite.com console + +# Backup site +docker compose -f pwd.yml exec backend bench --site mysite.com backup --with-files ``` ## Docker Concepts: Bind Mounts ### What Are Bind Mounts? -Bind mounts directly connect a file/directory on your host machine to a file/directory inside a container, creating real-time synchronization. +Bind mounts create a direct connection between a directory on your host machine and a directory inside a container. Changes in either location are immediately reflected in the other - perfect for development where you want to edit code on your host and see changes in the container. -### Bind Mount Types +### Bind Mount vs Named Volume vs Anonymous Volume + +| Type | Syntax | Use Case | Persistence | +|------|--------|----------|-------------| +| **Bind Mount** | `./local/path:/container/path` | Development, config files | On host filesystem | +| **Named Volume** | `volume_name:/container/path` | Production data, databases | Docker-managed | +| **Anonymous Volume** | `/container/path` | Temporary/cache data | Docker-managed, auto-deleted | + +### Bind Mount Examples ```yaml -# Bind Mounts (Direct host path mapping) -volumes: - - /home/user/myproject:/app # Host path : Container path - - ./development:/home/frappe/frappe-bench/sites # Relative path +services: + backend: + volumes: + # Development: Edit code on host, run in container + - ./my_custom_app:/home/frappe/frappe-bench/apps/my_custom_app + + # Configuration: Override container config with host file + - ./custom-config.json:/home/frappe/frappe-bench/sites/common_site_config.json:ro # :ro = read-only + + # Logs: Access container logs on host for debugging + - ./logs:/home/frappe/frappe-bench/logs + + # Database (not recommended for production) + - ./data/mysql:/var/lib/mysql -# Named Volumes (Docker-managed storage) -volumes: - - db_data:/var/lib/mysql # Volume name : Container path + # Named volume for production database + db: + volumes: + - db_data:/var/lib/mysql # Managed by Docker, survives container deletion -# Anonymous Volumes (Temporary) volumes: - - /tmp # Just container path + db_data: # Define named volume ``` -### Development Use Cases +### Performance Optimization (macOS/Windows) +Docker on macOS/Windows uses a VM, making bind mounts slower. Use these flags: + ```yaml -# Development code editing volumes: - - ./my_custom_app:/home/frappe/frappe-bench/apps/my_custom_app - -# Configuration files -volumes: - - ./config/my-site.conf:/etc/nginx/sites-enabled/my-site.conf:ro - -# Database data (persistent) -volumes: - - ./data/mysql:/var/lib/mysql - -# Logs and debugging -volumes: - - ./logs:/home/frappe/frappe-bench/logs + # :cached - Host writes are buffered (good for general development) + - ./development:/home/frappe/frappe-bench:cached + + # :delegated - Container writes are buffered (best when container writes heavily) + - ./development:/home/frappe/frappe-bench:delegated + + # :consistent - Full synchronization (slowest but safest) + - ./development:/home/frappe/frappe-bench:consistent ``` -### Performance Options -```yaml -# For macOS/Windows -volumes: - - ./development:/home/frappe/frappe-bench:cached # Better performance - - ./development:/home/frappe/frappe-bench:delegated # Best for writes -``` +**Recommendation:** Use `:cached` for most development work on macOS/Windows. ## Fork Management Best Practices -### Setting Up Your Fork +### Initial Fork Setup ```bash -# Add upstream remote (one time) +# 1. Fork on GitHub (use the Fork button) + +# 2. Clone YOUR fork +git clone https://github.com/YOUR_USERNAME/frappe_docker +cd frappe_docker + +# 3. Add upstream remote (original repo) git remote add upstream https://github.com/frappe/frappe_docker.git -# Create development branch -git checkout -b my-development +# 4. Verify remotes +git remote -v +# origin https://github.com/YOUR_USERNAME/frappe_docker (your fork) +# upstream https://github.com/frappe/frappe_docker (original) + +# 5. Create development branch +git checkout -b my-custom-setup ``` -### Safe Areas for Customizations +### Safe Customization Zones + **✅ Safe (Won't conflict with upstream):** -- `development/` directory contents -- New compose override files (`compose.my-*.yaml`) -- New scripts in `scripts/` directory -- New documentation files in `docs/` -- `.env.local` files +``` +development/ # Your entire dev environment + ├── frappe-bench/ # Local installation + └── .vscode/ # Your editor settings -**⚠️ Risky (May conflict):** -- `compose.yaml` - Core compose file -- `docker-bake.hcl` - Build configuration -- Existing scripts - -**❌ Avoid modifying:** -- Core Dockerfiles in `images/` -- Main configuration files - -### Sync Strategy -```bash -# Sync with upstream -git checkout main -git pull upstream main -git checkout my-development -git rebase main +compose.my-*.yaml # Your custom compose overrides +scripts/my-*.sh # Your custom scripts +docs/my-*.md # Your custom documentation +.env.local # Local environment overrides +.gitignore.local # Additional gitignore rules ``` -### Custom Environment Setup +**⚠️ Modification Needed (May conflict):** +``` +compose.yaml # Core - use overrides instead +docker-bake.hcl # Build config - use custom files +images/*/Dockerfile # Core images - extend rather than modify +``` + +**❌ Never Modify (Will break upstream sync):** +``` +.github/workflows/ # CI/CD pipelines +images/production/ # Production containers +resources/ # Core templates +``` + +### Keeping Fork Updated +```bash +# Regularly sync with upstream (weekly recommended) +git checkout main +git fetch upstream +git merge upstream/main +git push origin main + +# Update your development branch +git checkout my-custom-setup +git rebase main # Or: git merge main + +# If conflicts occur during rebase: +# 1. Fix conflicts in files +# 2. git add +# 3. git rebase --continue +# Or: git rebase --abort (to cancel) +``` + +### Custom Environment Pattern +Create override files for your customizations: + ```yaml # compose.my-env.yaml version: "3.7" @@ -295,104 +406,474 @@ version: "3.7" services: backend: environment: - - MY_CUSTOM_VAR=value + # Your custom environment variables + - DEVELOPER_MODE=true + - MY_API_KEY=${MY_API_KEY} volumes: - - ./development/my_custom_scripts:/home/frappe/my_scripts + # Your custom bind mounts + - ./development/my-scripts:/home/frappe/my-scripts + - ./development/my-config:/home/frappe/config - my-custom-service: - image: redis:alpine + # Your additional services + my-monitoring: + image: prom/prometheus + ports: + - "9090:9090" + volumes: + - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml + +# Use it: +# docker compose -f compose.yaml -f compose.my-env.yaml up ``` ### .gitignore Strategy +Add to `.gitignore` (or create `.gitignore.local`): + ```gitignore -# Add to existing .gitignore +# Local environment files .env.local -development/sites/* -development/apps/* -!development/apps.json -development/logs/ +*.local.yaml +compose.my-*.yaml + +# Development artifacts +development/frappe-bench/sites/* +development/frappe-bench/apps/* +!development/frappe-bench/apps.json +development/frappe-bench/logs/ +development/frappe-bench/env/ + +# Local customizations my-local-configs/ -compose.my-env.yaml.local +scripts/my-*.sh +docs/internal-*.md + +# IDE +.vscode/settings.json.local +.idea/ + +# Temporary files +*.swp +*.swo +*~ +.DS_Store +``` + +### Contributing Back to Upstream +```bash +# 1. Create feature branch from main +git checkout main +git pull upstream main +git checkout -b feature/my-improvement + +# 2. Make changes and commit +git add . +git commit -m "feat: add awesome feature" + +# 3. Push to YOUR fork +git push origin feature/my-improvement + +# 4. Create Pull Request on GitHub +# Go to: https://github.com/frappe/frappe_docker +# Click "Compare & pull request" ``` ## Quick Start Examples -### 1. Quick Test (pwd.yml) +### 1. Quick Test (5 minutes) +**Goal:** Try Frappe/ERPNext without any local setup + ```bash -# Clone and test +# Clone and run git clone https://github.com/frappe/frappe_docker cd frappe_docker docker compose -f pwd.yml up -d -# Follow site creation +# Monitor setup progress (~5 minutes) docker compose -f pwd.yml logs -f create-site -# Access: http://localhost:8080 -# Login: Administrator / admin +# When complete, access: +# URL: http://localhost:8080 +# Username: Administrator +# Password: admin + +# Cleanup when done +docker compose -f pwd.yml down -v ``` -### 2. Development Setup +### 2. Development Environment (15 minutes) +**Goal:** Set up for daily development with hot-reload + ```bash # Copy devcontainer config cp -R devcontainer-example .devcontainer -# Open in VSCode with Dev Containers extension -# Run installer inside container +# Open in VSCode +# 1. Install "Dev Containers" extension +# 2. Command Palette (Ctrl+Shift+P) → "Reopen in Container" +# 3. Wait for container build (~5 min first time) + +# Inside container terminal: cd /workspace/development -python installer.py --site-name mysite.localhost +python installer.py -# Access development files in development/frappe-bench/ +# Follow prompts: +# - Site name: development.localhost +# - Install ERPNext: Yes +# - Version: version-15 + +# Start development server +cd frappe-bench +bench start + +# Access: http://localhost:8000 +# Edit files in: development/frappe-bench/apps/ ``` -### 3. Custom App Development +### 3. Custom App Development (30 minutes) +**Goal:** Create and develop a custom Frappe application + ```bash +# Prerequisite: Complete Example 2 first + # Inside development container -bench new-app my_erp_customization -bench --site mysite.localhost install-app my_erp_customization +cd /workspace/development/frappe-bench -# Edit files in development/frappe-bench/apps/my_erp_customization/ +# Create new app +bench new-app library_management +# Follow prompts (title, description, publisher, etc.) + +# Install to site +bench --site development.localhost install-app library_management + +# Create DocTypes via web UI: +# 1. Go to: http://localhost:8000 +# 2. Setup → Customize → DocType → New +# 3. Create: Book, Author, Borrower, etc. + +# Or create via code: +# Edit: apps/library_management/library_management/library_management/doctype/ + +# Build and reload +bench build --app library_management +# Server auto-reloads (bench start watches for changes) ``` -### 4. Production Deployment +### 4. Production Deployment (1 hour) +**Goal:** Deploy Frappe in production with SSL + ```bash -# Use single-server example -# Follow docs/single-server-example.md -# Customize with compose overrides as needed +# Follow detailed guide +# See: docs/single-server-example.md + +# Quick overview: +# 1. Setup server with Docker +# 2. Clone frappe_docker +# 3. Configure environment variables +# 4. Use compose.yaml + production overrides +# 5. Setup SSL with Traefik/Let's Encrypt +# 6. Deploy and monitor + +# Key files: +# - compose.yaml +# - compose.mariadb.yaml +# - compose.redis.yaml +# - compose.proxy.yaml +# - compose.https.yaml + +# Deploy command: +docker compose \ + -f compose.yaml \ + -f overrides/compose.mariadb.yaml \ + -f overrides/compose.redis.yaml \ + -f overrides/compose.https.yaml \ + up -d ``` -## Resources and References +### 5. Multi-Site Hosting +**Goal:** Host multiple Frappe sites on one server -### Documentation -- [Frappe Framework Docs](https://frappeframework.com/docs) -- [ERPNext Documentation](https://docs.erpnext.com) -- [Docker Documentation](https://docs.docker.com) - -### Key Files in This Repository -- [`docs/development.md`](docs/development.md) - Development setup guide -- [`docs/single-server-example.md`](docs/single-server-example.md) - Production deployment -- [`development/installer.py`](development/installer.py) - Automated setup script -- [`pwd.yml`](pwd.yml) - Quick test configuration - -### Useful Commands ```bash -# Container management -docker compose logs -f -docker compose exec bash -docker compose ps -docker compose down +# See: docs/port-based-multi-tenancy.md -# Bench commands (inside container) -bench list-sites -bench list-apps -bench new-site -bench install-app -bench migrate -bench build +# Quick example: +# 1. Create multiple sites in development +bench new-site site1.com +bench new-site site2.com + +# 2. Configure Nginx/Traefik for routing +# 3. Each site gets own database +# 4. Shared Redis and application code ``` --- -*This guide covers the essentials for Django developers transitioning to Frappe Docker development. For specific use cases or advanced topics, refer to the official documentation or create additional guides in this docs/ directory.* +## Framework Comparisons -*Last updated: October 2025* -*Author: Development Team* \ No newline at end of file +> **Note:** This section provides comparisons to other frameworks for developers familiar with them. If you're new to all frameworks, you can skip this section - the rest of the guide is self-contained. + +### Frappe vs Django Concepts + +#### Project Structure Comparison + +**Django Project:** +```python +myproject/ +├── myproject/ # Project settings +│ ├── settings.py +│ ├── urls.py +│ └── wsgi.py +├── blog/ # Django app +│ ├── models.py +│ ├── views.py +│ └── urls.py +├── shop/ # Django app +└── users/ # Django app +``` + +**Frappe Bench:** +``` +bench/ +├── apps/ +│ ├── frappe/ # Core framework (comparable to Django itself) +│ ├── erpnext/ # Complete business app (like Django + DRF + Celery + admin) +│ ├── hrms/ # HR Management app +│ └── my_custom_app/ # YOUR custom app +└── sites/ + └── mysite.com/ # Site instance (like Django project + database) + ├── site_config.json + └── private/files/ +``` + +#### Conceptual Mapping + +| Django | Frappe | Notes | +|--------|--------|-------| +| Model | DocType | But includes UI, permissions, API automatically | +| View | Controller method | Much less code needed | +| Admin | Desk | More powerful, auto-generated | +| DRF Serializer | Built-in | Automatic from DocType | +| Celery task | Background job | Built-in, no separate setup | +| signals | hooks.py | More structured | +| Management command | bench command | More discoverable | + +#### Key Architectural Differences + +1. **Multi-tenancy** + - Django: One app = one database (typically) + - Frappe: One installation = many sites, each with own database + +2. **Background Jobs** + - Django: Requires Celery + Redis + worker setup + - Frappe: Built-in queue system, just use `enqueue()` + +3. **Real-time** + - Django: Requires Channels + Redis + ASGI setup + - Frappe: Socket.IO built-in, automatic for DocType updates + +4. **Admin/Management** + - Django: Admin for models, basic CRUD + - Frappe: Full-featured Desk with reports, dashboards, permissions + +5. **API** + - Django: Manual DRF setup, serializers, views + - Frappe: Automatic REST + RPC from DocType definitions + +#### Code Comparison Example + +**Creating a "Customer" model:** + +Django (requires ~50+ lines): +```python +# models.py +class Customer(models.Model): + name = models.CharField(max_length=100) + email = models.EmailField(unique=True) + +# serializers.py +class CustomerSerializer(serializers.ModelSerializer): + # ... + +# views.py +class CustomerViewSet(viewsets.ModelViewSet): + # ... + +# urls.py +router.register(r'customers', CustomerViewSet) + +# admin.py +@admin.register(Customer) +class CustomerAdmin(admin.ModelAdmin): + # ... +``` + +Frappe (DocType JSON + ~10 lines Python): +```json +// customer.json (auto-generated via UI or code) +{ + "name": "Customer", + "fields": [ + {"fieldname": "customer_name", "fieldtype": "Data"}, + {"fieldname": "email", "fieldtype": "Data", "unique": 1} + ] +} +``` +```python +# customer.py (only for custom business logic) +import frappe +from frappe.model.document import Document + +class Customer(Document): + def validate(self): + # Custom validation logic only + pass +``` + +✅ **Automatically includes:** +- REST API (`/api/resource/Customer`) +- List view, Form view +- Search, Filters, Sorting +- Permissions (Create, Read, Update, Delete) +- Audit trail (created_by, modified_by, versions) +- Print formats, Email templates + +#### When to Choose Frappe vs Django + +**Choose Frappe when:** +- Building business applications (ERP, CRM, project management) +- Need multi-tenancy out-of-the-box +- Want rapid development with auto-generated UI +- Need role-based permissions and workflows +- Building for non-technical users who need customization + +**Choose Django when:** +- Building consumer web apps (social media, e-commerce frontend) +- Need full control over every aspect +- Have highly custom UI requirements +- Team is already Django-expert +- Building API-only services + +**Hybrid Approach:** +Many teams use both: Frappe for back-office/admin tools, Django for customer-facing web apps. + +--- + +## Resources and References + +### Official Documentation +- [Frappe Framework Docs](https://frappeframework.com/docs) - Core framework documentation +- [Frappe Docker Docs](https://github.com/frappe/frappe_docker/tree/main/docs) - This repository's docs +- [ERPNext Documentation](https://docs.erpnext.com) - ERPNext user and developer docs +- [Docker Documentation](https://docs.docker.com) - Docker fundamentals + +### Key Files in This Repository +- [`docs/development.md`](development.md) - Detailed development setup +- [`docs/single-server-example.md`](single-server-example.md) - Production deployment guide +- [`docs/site-operations.md`](site-operations.md) - Common site management tasks +- [`development/installer.py`](../development/installer.py) - Automated setup script +- [`pwd.yml`](../pwd.yml) - Quick test configuration +- [`compose.yaml`](../compose.yaml) - Base Docker Compose configuration + +### Community Resources +- [Frappe Forum](https://discuss.frappe.io) - Community Q&A +- [Frappe School](https://frappe.school) - Video tutorials +- [Frappe GitHub](https://github.com/frappe/frappe) - Framework source code + +### Essential Docker Commands Reference +```bash +# Service Management +docker compose up -d # Start all services in background +docker compose down # Stop and remove containers +docker compose down -v # Stop and remove volumes (data loss!) +docker compose restart # Restart specific service +docker compose ps # List running services +docker compose logs -f # Follow logs for service + +# Container Access +docker compose exec bash # Open shell in running container +docker compose exec # Run command in container +docker compose run # Run one-off command (creates new container) + +# Debugging +docker compose logs --tail=100 # Last 100 log lines +docker compose top # Show running processes +docker inspect # Detailed container info + +# Cleanup +docker system prune # Remove unused containers/networks +docker volume prune # Remove unused volumes (BE CAREFUL!) +docker image prune # Remove unused images +``` + +### Essential Bench Commands Reference +```bash +# Site Operations +bench new-site # Create new site +bench drop-site # Delete site (asks confirmation) +bench list-sites # List all sites +bench use # Set default site + +# App Operations +bench get-app # Download app from git +bench get-app # Download from Frappe registry +bench install-app # Install to default site +bench install-app --site # Install to specific site +bench uninstall-app # Uninstall from default site +bench list-apps # List installed apps + +# Development +bench start # Start development server (hot-reload) +bench build # Build frontend assets +bench build --app # Build specific app +bench migrate # Run database migrations +bench clear-cache # Clear Redis cache +bench clear-website-cache # Clear website route cache + +# Database +bench mariadb # Open MariaDB console +bench backup # Backup default site +bench backup --with-files # Backup with uploaded files +bench restore # Restore backup + +# Code Generation +bench new-app # Create new app +bench --site console # Python REPL with Frappe context +bench --site execute "" # Execute Python code + +# Deployment +bench setup production # Setup for production (supervisor, nginx) +bench restart # Restart bench processes +bench update # Update framework and apps +``` + +### Troubleshooting Quick Reference + +| Issue | Solution | +|-------|----------| +| Port 8080 already in use | Change `PWD_PORT` in `.env` or stop other service | +| Container won't start | Check logs: `docker compose logs ` | +| Site creation fails | Check `create-site` logs, ensure DB is ready | +| Can't connect to site | Wait 5 min for initialization, check container health | +| Permission errors | Check volume permissions, may need `chown` | +| Out of disk space | `docker system prune -a --volumes` (CAREFUL!) | +| Python packages missing | `bench pip install ` inside container | +| Frontend not building | `bench build --force`, check Node.js errors | +| Database connection fails | Check `common_site_config.json`, Redis/MariaDB status | + +### Getting Help + +1. **Check existing docs** - Most issues covered in [`docs/troubleshoot.md`](troubleshoot.md) +2. **Search Frappe Forum** - [discuss.frappe.io](https://discuss.frappe.io) +3. **GitHub Issues** - Search existing issues first +4. **Discord/Telegram** - Community real-time chat (links in main repo) + +### Contributing + +Found issues or improvements for this guide? +- Create an issue: [frappe_docker/issues](https://github.com/frappe/frappe_docker/issues) +- Submit a PR: See [CONTRIBUTING.md](../CONTRIBUTING.md) + +--- + +*This guide provides a comprehensive overview of Frappe Docker for developers of all backgrounds. For specific use cases or advanced topics, refer to the linked documentation.* + +*Last updated: October 2025* \ No newline at end of file