diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3cc671ee..3389cfe0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,45 @@ On each PR that contains changes relevant to Docker builds, images are being bui > :evergreen_tree: Please be considerate when pushing commits and opening PR for multiple branches, as the process of building images uses energy and contributes to global warming. +## Pull Request Process + +1. Test builds locally before submitting +2. Follow conventional commit format +3. Update documentation if needed +4. Ensure all pre-commit checks pass +5. Reference related issues in PR description + +## Commit Message Convention + +We recommend [Conventional Commits](https://www.conventionalcommits.org/) for clear and semantic commit history. + +Format: `(): ` + +**Types:** + +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation changes +- `style`: Code style changes (formatting, missing semicolons, etc.) +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `chore`: Maintenance tasks (dependencies, build config, etc.) +- `ci`: CI/CD changes + +**Examples:** + +``` +chore(deps): bump wkhtmltopdf version +fix(ci): correct buildx cache configuration +docs(contributing): add conventional commits guidelines +``` + +## Branch Naming + +- `feature/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation updates + ## Lint We use `pre-commit` framework to lint the codebase before committing. diff --git a/README.md b/README.md index 1296dd5d..6619e4d2 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,66 @@ +# Frappe Docker + [![Build Stable](https://github.com/frappe/frappe_docker/actions/workflows/build_stable.yml/badge.svg)](https://github.com/frappe/frappe_docker/actions/workflows/build_stable.yml) [![Build Develop](https://github.com/frappe/frappe_docker/actions/workflows/build_develop.yml/badge.svg)](https://github.com/frappe/frappe_docker/actions/workflows/build_develop.yml) -Everything about [Frappe](https://github.com/frappe/frappe) and [ERPNext](https://github.com/frappe/erpnext) in containers. +Docker images and orchestration for Frappe applications. -# Getting Started +## What is this? + +This repository handles the containerization of the Frappe stack, including the application server, database, Redis, and supporting services. It provides quick disposable demo setups, a development environment, production-ready Docker images and compose configurations for deploying Frappe applications including ERPNext. + +## Repository Structure + +``` +frappe_docker/ +├── docs/ # Complete documentation +├── overrides/ # Docker Compose configurations for different scenarios +├── compose.yaml # Base Compose File for production setups +├── pwd.yml # Single Compose File for quick disposable demo +├── images/ # Dockerfiles for building Frappe images +├── development/ # Development environment configurations +├── devcontainer-example/ # VS Code devcontainer setup +└── resources/ # Helper scripts and configuration templates +``` + +> This section describes the structure of **this repository**, not the Frappe framework itself. + +### Key Components + +- `docs/` - Canonical documentation for all deployment and operational workflows +- `overrides/` - Opinionated Compose overrides for common deployment patterns +- `compose.yaml` - Base compose file for production setups (production) +- `pwd.yml` - Disposable demo environment (non-production) + +## Documentation + +**The official documentation for `frappe_docker` is maintained in the `docs/` folder in this repository.** **New to Frappe Docker?** Read the [Getting Started Guide](docs/getting-started.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). +If you are already familiar with Frappe, you can jump right into the [different deployment methods](docs/01-getting-started/01-choosing-a-deployment-method.md) and select the one best suited to your use case. -Once completed, chose one of the following two sections for next steps. +## Prerequisites -### Try in Play With Docker +- [Docker](https://docs.docker.com/get-docker/) +- [Docker Compose v2](https://docs.docker.com/compose/) +- [git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git) -To play in an already set up sandbox, in your browser, click the button below: +> For Docker basics and best practices refer to Docker's [documentation](http://docs.docker.com) + +## Demo setup + +The fastest way to try Frappe is to play in an already set up sandbox, in your browser, click the button below: Try in PWD -### Try on your Dev environment +### Try on your environment + +> **⚠️ Disposable demo only** +> +> **This setup is intended for quick evaluation. Expect to throw the environment away.** You will not be able to install custom apps to this setup. For production deployments, custom configurations, and detailed explanations, see the full documentation. First clone the repo: @@ -28,28 +69,15 @@ git clone https://github.com/frappe/frappe_docker cd frappe_docker ``` -Then run: `docker compose -f pwd.yml up -d` +Then run: -### To run on ARM64 architecture follow this instructions +```sh +docker compose -f pwd.yml up -d +``` -After you clone the repo and `cd frappe_docker`, run this command to build multi-architecture images specifically for ARM64. +Wait for a couple of minutes for ERPNext site to be created or check `create-site` container logs before opening browser on port `8080`. (username: `Administrator`, password: `admin`) -`docker buildx bake --no-cache --set "*.platform=linux/arm64"` - -and then - -- add `platform: linux/arm64` to all services in the `pwd.yml` -- replace the current specified versions of erpnext image on `pwd.yml` with `:latest` - -Then run: `docker compose -f pwd.yml up -d` - -## Final steps - -Wait for 5 minutes for ERPNext site to be created or check `create-site` container logs before opening browser on port 8080. (username: `Administrator`, password: `admin`) - -If you ran in a Dev Docker environment, to view container logs: `docker compose -f pwd.yml logs -f create-site`. Don't worry about some of the initial error messages, some services take a while to become ready, and then they go away. - -# Documentation +## Documentation Links ### [Getting Started Guide](docs/getting-started.md) @@ -57,54 +85,26 @@ If you ran in a Dev Docker environment, to view container logs: `docker compose ### [Getting Started](#getting-started) -- [Quick Start (Linux/Mac)](docs/01-getting-started/01-quick-start-linux-mac.md) -- [Single Compose Setup](docs/01-getting-started/02-single-compose-setup.md) +### [Deployment Methods](docs/01-getting-started/01-choosing-a-deployment-method.md) -### [Setup](#setup) +### [ARM64](docs/01-getting-started/03-arm64.md) -- [Container Setup Overview](docs/02-setup/01-overview.md) -- [Build Setup](docs/02-setup/02-build-setup.md) -- [Start Setup](docs/02-setup/03-start-setup.md) -- [Environment Variables](docs/02-setup/04-env-variables.md) -- [Compose Overrides](docs/02-setup/05-overrides.md) -- [Setup Examples](docs/02-setup/06-setup-examples.md) -- [Single Server Example](docs/02-setup/07-single-server-example.md) +### [Container Setup Overview](docs/02-setup/01-overview.md) -### [Production](#production) +### [Development](docs/05-development/01-development.md) -- [TLS/SSL Setup](docs/03-production/01-tls-ssl-setup.md) -- [Backup Strategy](docs/03-production/02-backup-strategy.md) -- [Multi-Tenancy](docs/03-production/03-multi-tenancy.md) +## Contributing -### [Operations](#operations) - -- [Site Operations](docs/04-operations/01-site-operations.md) - -### [Development](#development) - -- [Development Guide](docs/05-development/01-development.md) -- [Debugging](docs/05-development/02-debugging.md) -- [Local Services Connection](docs/05-development/03-local-services-connection.md) - -### [Migration](#migration) - -- [Migrate from Multi-Image Setup](docs/06-migration/01-migrate-from-multi-image-setup.md) - -### [Troubleshooting](#troubleshooting) - -- [Troubleshoot Guide](docs/07-troubleshooting/01-troubleshoot.md) -- [Windows Nginx Entrypoint Error](docs/07-troubleshooting/02-windows-nginx-entrypoint-error.md) - -### [Reference](#reference) - -- [Build Version 10 Images](docs/08-reference/01-build-version-10-images.md) - -# Contributing - -If you want to contribute to this repo refer to [CONTRIBUTING.md](CONTRIBUTING.md) +Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. This repository is only for container related stuff. You also might want to contribute to: -- [Frappe framework](https://github.com/frappe/frappe#contributing), -- [ERPNext](https://github.com/frappe/erpnext#contributing), +## Resources + +- [Frappe framework](https://github.com/frappe/frappe), +- [ERPNext](https://github.com/frappe/erpnext), - [Frappe Bench](https://github.com/frappe/bench). + +## License + +This repository is licensed under the MIT License. See [LICENSE](LICENSE) for details. diff --git a/docs/01-getting-started/03-quick-start-linux-mac.md b/docs/01-getting-started/03-arm64.md similarity index 92% rename from docs/01-getting-started/03-quick-start-linux-mac.md rename to docs/01-getting-started/03-arm64.md index a224e9fe..d2c50ce0 100644 --- a/docs/01-getting-started/03-quick-start-linux-mac.md +++ b/docs/01-getting-started/03-arm64.md @@ -1,18 +1,28 @@ # How to install ERPNext on linux/mac using Frappe_docker ? -step1: clone the repo +## Clone the repo -``` +```sh git clone https://github.com/frappe/frappe_docker +cd frappe_docker ``` -step2: add platform: linux/amd64 to all services in the /pwd.yaml +## buildx platform -here is the update pwd.yml file +Run this command to build multi-architecture images specifically for ARM64: + +```sh +docker buildx bake --no-cache --set "*.platform=linux/arm64" +``` + +## add platform to all services + +- add platform: `linux/arm64` to all services in the `pwd.yml` +- (replace the current specified versions of erpnext image on `pwd.yml` with `:latest`) + +here is the example pwd.yml file: ```yml -version: "3" - services: backend: image: frappe/erpnext:v15 @@ -209,14 +219,10 @@ volumes: logs: ``` -step3: run the docker +## Run the compose file -``` -cd frappe_docker -``` - -``` -docker-compose -f ./pwd.yml up +```sh +docker compose -f pwd.yml up ``` ---