Architecture

frappe-manager Python Package

• This package introduces fm command
• This package serves as the entry point for the FrappeManager project and provides the following key functionalities:

1. Metadata Generation: Generates essential metadata required for setting up a Bench environment, including sitename, admin password, and the list of Frappeverse apps to be installed.

2. Docker Compose Configuration: Customizes and generates a Docker Compose project using the metadata as input for the entrypoint script. This project contains various services to support Frappe development.

3. Docker Compose Management: Wraps the Docker Compose CLI to manage the Docker Compose project, allowing for easy control and orchestration of containers for the development environment.

4. Environment Management Commands: Provides commands to manage the FrappeManager environment, streamlining common development tasks.

5. CLI Directory Creation: Creates a directory at ~/frappe to store frappe-manager managed sites. This directory contains the following subdirectories:

   • logs: Stores cli logs.
   • sites: Stores the Docker Compose project for sites.
   • migration: Stores migration backups.
   • archived: Stores failed migrated sites.
   • services: Stores the Docker Compose project for services.

Docker Compose Project: services

Located at ~/frappe/services, this project includes two services:

1. global-db:

• This service serves as the central database for all sites. All site databases are stored here. The service uses the mariadb:10.6 image.
• The database credentials and configuration are stored in Docker secrets.
• The following directories are mounted for this service:

• fm-global-db-data volume to /var/lib/mysql for database data (OSX) or ./mariadb/data to /var/lib/mysql (Linux)
• ./mariadb/conf to /etc/mysql for configuration files
• ./mariadb/logs to /var/log/mysql for log files

2. global-nginx-proxy:

• This service functions as a reverse proxy for all sites and exposes host ports 80 and 443. It uses the jwilder/nginx-proxy image and restarts automatically.
• The following directories are mounted for this service:

• ./nginx-proxy/certs to /etc/nginx/certs for SSL certificates
• ./nginx-proxy/dhparam to /etc/nginx/dhparam for Diffie-Hellman parameters
• ./nginx-proxy/confd to /etc/nginx/conf.d for additional configuration files
• ./nginx-proxy/htpasswd to /etc/nginx/htpasswd for HTTP Basic Authentication
• ./nginx-proxy/vhostd to /etc/nginx/vhost.d for vhost configuration
• ./nginx-proxy/html to /usr/share/nginx/html for static HTML files
• ./nginx-proxy/logs to /var/log/nginx for log files
• ./nginx-proxy/run to /var/run for PID files
• ./nginx-proxy/cache to /var/cache/nginx for caching
• /var/run/docker.sock to /tmp/docker.sock:ro for Docker socket

Implementation differences between OSX and Linux

OSX

The user directive in Docker Compose is not utilized in OSX because the osxfs file system driver automatically handles UID/GID remapping. This ensures that files created within the container maintain the correct permissions when accessed from the host, and vice versa.

global-db: For data persistence, a Docker volume mount (fm-global-db-data) is used instead of a bind mount(causes issues on macOS).

Linux

On Linux, the user directive is used to specify the user (and group) under which the container runs. This is often necessary to prevent permission issues on Linux.

global-db: A bind mount (./mariadb/data) is used for data persistence.

Docker compose project for each site

The Docker Compose project includes the following services:

• Frappe (custom build):

  • Configures the server environment, including setting up pyenv and server-specific configurations.
  • Creates a Bench environment for Frappe app development.
  • Installs required Frappeverse apps.
  • Creates and manages Frappe sites with associated databases.
  • Initiates Supervisor as the init process, containing a service for starting the Frappe development server.

• Nginx (custom build):

  • Extends the features of the official Nginx Docker image.
  • Incorporates input from the frappe-manager Python package to create site-specific Nginx configurations from templates.

• Adminer: A fully-featured database management tool, serving as an alternative to phpMyAdmin for database management.

• Mailhog: An email testing tool with a fake SMTP server underneath, enabling email testing during development.

• redis-cache, redis-queue, redis-socketio: They set up Redis servers for caching, queuing, and real-time communication.

• socketio: It sets up a Socket.IO server for real-time communication.

• schedule: It sets up a scheduler for running background tasks.

CLI logs

• Stored in /home/<user>/frappe/logs/fm.log
• Logs contains:
  • every fm command invoked by user.
  • executed docker commands, command output and return code.
  • exception happend during runtime.
• Logs are rotated when the log size hits 10MB, creates files like fm.log.1 when rotate limit is reached and only 3 such files are kept.