Skip to main content

Reference: Backing Up, Restoring, and Resetting the L7|ESP Application

Overview

A standard ESP installation consists of 2 stateful aspects:

  1. Filesystem volumes

    1. data volume - containing configuration, logs, uploaded and generated files, etc.

    2. static volume - containing the frontend files, including custom JavaScript extensions

  2. PostgreSQL Database

The steps needed to back up, restore, and reset L7|ESP can vary based on how it is deployed. Developers will typically use the Docker engine, Docker Compose deployment style. A PostgreSQL database is also packaged in the default L7|ESP container, intended for development use. Production and Test deployments can vary based on the needs of your organization, but often PostgreSQL will be a managed service supported by a cloud provider such as AWS or Azure. Cloud providers provide their own tooling for backing up filesystem and database, and it is recommended to follow their guidance on using those tools.

The remainder of this guide will describe a general process for backing up, restoring, and resetting L7|ESP, from the perspective of a developer using Docker Compose. Similar principles will apply to other deployment methods, but other tooling exists and may be more appropriate for the given infrastructure.

Content and Customizations Considerations

While the database backup will capture any user-driven customizations created in L7|Master (previously L7|Builders), all user-driven customizations are ideally exported using the espclient Python command line package or packaged into an L7|Hub bundle. Exported content and customizations can be put into standard installation files which can be propagated to other instances of L7|ESP. Ideally, these customizations should be reconciled and merged with the existing source controlled project files (typically hosted in a cloud-based version control provider like GitHub, BitBucket, etc.).

One espclient command that can be used to export the content definitions from the database is esp dump. The following is a quickstart guide for using this command:

### Inside the L7|ESP Container, `docker-compose exec server bash` for Docker Compose deployments # Activate the Python environment - necessary for L7|ESP 3.0 and lower source ~/data/extensions/client/bin/activate # see the help for `esp` and `esp dump` esp --help esp dump --help # For non-development environments, the unique password for the primary admin (admin@localhost) will be needed esp --password admin_at_localhost_password status # Test the login # Dump *all* the content definitions from the database into their file-based equivalents esp --password admin_at_localhost_password dump -r dumps -s seed.yml # Creates a folder "dumps" for exported definitions, with a seed file "seed.yml" # For targeted export of only certain models, additional flags can be provided # Best to use these flags when the area of changes is known, as it provides a smaller changeset to examine esp --password admin_at_localhost_password dump -r dumps -s seed.yml --model Item --model SampleType --model Protocol --model Workflow # as many models as needed can be specified # A configuration file can also be used to run the `esp dump` command above for commonly used exports (see esp dump help)

Backup & Restore

These steps are ideally performed while the system is idle and/or stopped (l7 stop inside the L7|ESP application). All Pipelines should be in a completed state (no pipelines in Running state). Users should not be active in the system. A backup cannot capture and resume open transactions (running process state), so this activity is best performed or scheduled after hours.

A database backup can be taken using standard PostgreSQL tooling. This tooling is packaged as a command line utility inside the L7|ESP container.

PostgreSQL - Chapter 26 - Backup and Restore

PostgreSQL - pg_dump

PostgreSQL - pg_restore

Note: Links are to the most recent release of PostgreSQL. For the most accurate information, select your version of PostgreSQL (L7|ESP 3.0 default PG10, L7|ESP 3.1/3.2 default PG13).

All commands executed from inside the L7|ESP Container

Backup

  1. Create a backup directory

  2. Backup the database (local DB with the container image)

    1. pg_dump --host localhost --port 1487 --dbname lab7 --clean --if-exists --format=c > ./esp_db_20230302.pgdump*Use today’s date in ISO format

  3. Backup the shared data volume. Not all folders need to be copied.

    1. rsync --verbose --archive --exclude 'log/' --exclude 'run/' --exclude 'database/' --exclude 'project/' ~/data/ ./

Note: Remote databases will have different connection parameters. Confirm port, user, password, database name, and networking to ensure a connection can be established.

Reset

Note: Be sure to copy the above backups to a persistent location outside of the L7|ESP container

For Docker Compose environments using the internal development PostgreSQL, the ~/data/database folder contains all the PostgreSQL data. With the backups in hand, the Docker volumes can be dropped and recreated as a simple way to reset the database:

Drop and recreate the database by running docker-compose down --volumes followed by docker-compose up --detach

For external database servers, the existing lab7 database can be renamed or deleted once a backup has been made. Alternatively, a new database server could also be provisioned and setup following the instructions for Database Configuration.

If choosing not to drop the database volumes, to reset the database to the base state prior to install:

# From inside the esp container # Stop all services except the database service l7 stop $(l7 status | grep -v database | grep RUNNING | awk '{print $1}') # Clear and recreate the database # Update connection parameters as needed psql -h localhost -p 1487 -d postgres << EOF DROP DATABASE lab7; CREATE DATABASE lab7; CREATE ROLE esp; GRANT ALL PRIVILEGES ON DATABASE lab7 TO esp; EOF # Run initial migrations to set up the schema l7 init --yes # Follow restore steps if restoring # Finish by triggering the Ansible-based install via `make install` from the project folder make install

Restore

  1. Stop all L7|ESP services except for the database

    1. l7 stop $(l7 status | grep -v database | grep RUNNING | awk '{print $1}')

  2. Restore the database

    1. pg_restore --host localhost --port 1487 --dbname lab7 --clean --if-exists --no-owner ./<backup_file>

  3. Restore the shared data volume

    1. rsync -avh ./* ~/data/

  4. Run make install to reinstall all content, or at a minimum make clientext to ensure frontend JavaScript extensions are in place

Reference Documents:

Database Configuration

Backup and Disaster Recovery

Related Training:

L7 University - L7|ESP: Installation, Setup, and Tuning

L7 University - L7|ESP Developer MasterClass