frappe_docker/docs/site-operations.md

Site operations

Create and use env file to pass environment variables to containers,

source .env

Or specify environment variables instead of passing secrets as command arguments. Refer notes section for environment variables required

Setup New Site

Note:

• Wait for the MariaDB service to start before trying to create a new site.
  • If new site creation fails, retry after the MariaDB container is up and running.
  • If you're using a managed database instance, make sure that the database is running before setting up a new site.

# Create ERPNext site
docker run \
    -e "SITE_NAME=$SITE_NAME" \
    -e "DB_ROOT_USER=$DB_ROOT_USER" \
    -e "MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD" \
    -e "ADMIN_PASSWORD=$ADMIN_PASSWORD" \
    -e "INSTALL_APPS=erpnext" \
    -v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
    --network <project-name>_default \
    frappe/erpnext-worker:$VERSION new

Environment Variables needed:

• SITE_NAME: name of the new site to create. Site name is domain name that resolves. e.g. erp.example.com or erp.localhost.
• DB_ROOT_USER: MariaDB Root user.
• MYSQL_ROOT_PASSWORD: In case of the MariaDB docker container use the one set in MYSQL_ROOT_PASSWORD in previous steps. In case of a managed database use the appropriate password.
• MYSQL_ROOT_PASSWORD_FILE - When the MariaDB root password is stored using docker secrets.
• ADMIN_PASSWORD: set the administrator password for the new site.
• ADMIN_PASSWORD_FILE: set the administrator password for the new site using docker secrets.
• INSTALL_APPS=erpnext: available only in erpnext-worker and erpnext containers (or other containers with custom apps). Installs ERPNext (and/or the specified apps, comma-delinieated) on this new site.
• FORCE=1: optional variable which force installation of the same site.

Add sites to proxy

Change SITES variable to the list of sites created encapsulated in backtick and separated by comma with no space. e.g. SITES=`site1.example.com`,`site2.example.com` .

Reload variables with following command.

docker-compose up --project-name <project-name> -d

Backup Sites

Environment Variables

• SITES is list of sites separated by : colon to migrate. e.g. SITES=site1.domain.com or SITES=site1.domain.com:site2.domain.com By default all sites in bench will be backed up.
• WITH_FILES if set to 1, it will backup user-uploaded files.
• By default backup takes mariadb dump and gzips it. Example file, 20200325_221230-test_localhost-database.sql.gz
• If WITH_FILES is set then it will also backup public and private files of each site as uncompressed tarball. Example files, 20200325_221230-test_localhost-files.tar and 20200325_221230-test_localhost-private-files.tar
• All the files generated by backup are placed at volume location sites-vol:/{site-name}/private/backups/*

docker run \
    -e "SITES=site1.domain.com:site2.domain.com" \
    -e "WITH_FILES=1" \
    -v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
    --network <project-name>_default \
    frappe/erpnext-worker:$VERSION backup

The backup will be available in the sites-vol volume.

Push backup to s3 compatible storage

Environment Variables

• BUCKET_NAME, Required to set bucket created on S3 compatible storage.
• REGION, Required to set region for S3 compatible storage.
• ACCESS_KEY_ID, Required to set access key.
• SECRET_ACCESS_KEY, Required to set secret access key.
• ENDPOINT_URL, Required to set URL of S3 compatible storage.
• BUCKET_DIR, Required to set directory in bucket where sites from this deployment will be backed up.
• BACKUP_LIMIT, Optionally set this to limit number of backups in bucket directory. Defaults to 3.

 docker run \
    -e "BUCKET_NAME=backups" \
    -e "REGION=region" \
    -e "ACCESS_KEY_ID=access_id_from_provider" \
    -e "SECRET_ACCESS_KEY=secret_access_from_provider" \
    -e "ENDPOINT_URL=https://region.storage-provider.com" \
    -e "BUCKET_DIR=frappe-bench" \
    -v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
    --network <project-name>_default \
    frappe/frappe-worker:$VERSION push-backup

Note:

• Above example will backup files in bucket called backup at location frappe-bench-v12/site.name.com/DATE_TIME/DATE_TIME-site_name_com-{filetype}.{extension},
• example DATE_TIME: 20200325_042020.
• example filetype: database, files or private-files
• example extension: sql.gz or tar

Restore backups

Environment Variables

• MYSQL_ROOT_PASSWORD or MYSQL_ROOT_PASSWORD_FILE(when using docker secrets), Required to restore mariadb backups.
• BUCKET_NAME, Required to set bucket created on S3 compatible storage.
• ACCESS_KEY_ID, Required to set access key.
• SECRET_ACCESS_KEY, Required to set secret access key.
• ENDPOINT_URL, Required to set URL of S3 compatible storage.
• REGION, Required to set region for s3 compatible storage.
• BUCKET_DIR, Required to set directory in bucket where sites from this deployment will be backed up.

docker run \
    -e "MYSQL_ROOT_PASSWORD=admin" \
    -e "BUCKET_NAME=backups" \
    -e "REGION=region" \
    -e "ACCESS_KEY_ID=access_id_from_provider" \
    -e "SECRET_ACCESS_KEY=secret_access_from_provider" \
    -e "ENDPOINT_URL=https://region.storage-provider.com" \
    -e "BUCKET_DIR=frappe-bench" \
    -v <project-name>_sites-vol:/home/frappe/frappe-bench/sites \
    -v ./backups:/home/frappe/backups \
    --network <project-name>_default \
    frappe/frappe-worker:$VERSION restore-backup

Note:

• Volume must be mounted at location /home/frappe/backups for restoring sites
• If no backup files are found in volume, it will use s3 credentials to pull backups
• Backup structure for mounted volume or downloaded from s3:
  • /home/frappe/backups
    • site1.domain.com
      • 20200420_162000
        • 20200420_162000-site1_domain_com-*
    • site2.domain.com
      • 20200420_162000
        • 20200420_162000-site2_domain_com-*

Edit configs

Editing config manually might be required in some cases, one such case is to use Amazon RDS (or any other DBaaS). For full instructions, refer to the wiki. Common question can be found in Issues and on forum.

common_site_config.json or site_config.json from sites-vol volume has to be edited using following command:

docker run \
    -it \
    -v <project-name>_sites-vol:/sites \
    alpine vi /sites/common_site_config.json

Instead of alpine use any image of your choice.