RELECOV Platform

RELECOV Platform deployment guide (containers and bare-metal), including iSkyLIMS and Nextstrain integration.

RELECOV Platform

Get the code (required)

git clone https://github.com/bu-isciii/relecov-platform.git
cd relecov-platform

iSkyLIMS is required for the integrated platform stack:

cd ..
git clone https://github.com/bu-isciii/iskylims.git relecov-iskylims

Choose your path

Docker (test): full local stack for validation.
Docker (production): app + iSkyLIMS + Nextstrain containers pointing to your production DB.
Bare-metal: install directly on the host using install.sh.

Minimum requirements

Baseline software (minimum recommended):

MySQL 8.0+ or MariaDB 10.4+
Git 2.34+
Python 3.11+
Apache HTTP Server 2.4+ (for reverse proxy on production)
Docker Engine + Compose v2, or Podman 4.9+ + podman-compose
tar, rsync, wget, curl

Notes:

This guide does not cover MySQL installation itself, only DB/user/grant creation and operational tasks.
For container deployments with external DB, ensure network connectivity from containers to DB host/port.
For Podman, prefer host.containers.internal in DB host settings.

Docker deployment

Prerequisites:

Docker Compose v2 or Podman + podman-compose.
Both repositories checked out side-by-side:
- relecov-platform
- relecov-iskylims

Local test stack

Runs:

relecov_test_db (MySQL)
relecov_test_app (RELECOV Platform)
relecov_test_iskylims_app (iSkyLIMS)
relecov_test_nextstrain (Nextstrain viewer)

Basic test install:

cd relecov-platform
bash container_install.sh --test --engine podman 2>&1 | tee relecov_test_install.log

Per-service conf mapping (recommended):

bash container_install.sh --test --engine podman \
  --install_conf_map app,conf/docker_test_platform_settings.txt \
  --install_conf_map iskylims_app,conf/docker_test_iskylims_settings.txt \
  2>&1 | tee relecov_test_install.log

The container images now include the staged application trees for both relecov-platform and relecov-iskylims. Test containers can therefore be recreated or restarted without rerunning the file installation step; container_install.sh only runs the runtime bootstrap tasks inside each container.

Production container stack

Prepare production confs (separate for each service):

cp conf/docker_production_settings.txt conf/docker_production_platform_settings.txt
cp ../relecov-iskylims/conf/docker_production_settings.txt ../relecov-iskylims/conf/docker_production_iskylims_settings.txt

Edit both files with your production DB/network values.
Deploy:

cd relecov-platform
bash container_install.sh --engine podman \
  --action install \
  --install_conf_map app,conf/docker_production_platform_settings.txt \
  --install_conf_map iskylims_app,../relecov-iskylims/conf/docker_production_iskylims_settings.txt \
  2>&1 | tee relecov_prod_install.log

Endpoints:

RELECOV Platform: http://<host>:8000
iSkyLIMS: http://<host>:8001
Nextstrain: http://<host>:8100

Production images now bake the staged Django application trees into the images themselves. Host reboots or container recreation no longer require rerunning the app installation step; container_install.sh only performs runtime bootstrap tasks such as migrations, optional scripts, superuser creation on first install, and collectstatic.

Persist logs/documents on the host

For production container deployments, keep these paths persistent:

Logs: /var/log/local/apps/relecov-platform -> /opt/relecov-platform/logs
Apache logs: /var/log/local/apache -> /var/log/httpd
Apache config: ${APP_INSTALL_PATH:-/opt/relecov-platform}/conf/relecov_apache_reverse_proxy.conf -> /etc/httpd/conf.d/relecov.conf
Documents: named volume relecov_documents -> /opt/relecov-platform/documents
Static: /opt/relecov-platform/static-host -> /opt/relecov-platform/static

Prepare host directories and ownership:

sudo mkdir -p /var/log/local/apps/relecov-platform
sudo mkdir -p /var/log/local/apache
sudo mkdir -p ${APP_INSTALL_PATH:-/opt/relecov-platform}/conf
sudo mkdir -p /opt/relecov-platform/static-host
sudo chown -R ${APP_UID:-1212}:${APP_GID:-1212} /var/log/local/apps/relecov-platform /opt/relecov-platform/static-host ${APP_INSTALL_PATH:-/opt/relecov-platform}

Apache reverse proxy (container) + Gunicorn

For production, the app container runs gunicorn and the apache service in docker-compose.prod.yml acts as the reverse proxy for RELECOV Platform, iSkyLIMS, and Nextstrain.

During container_install.sh, the file conf/relecov_apache_reverse_proxy.conf is copied to ${APP_INSTALL_PATH:-/opt/relecov-platform}/conf/relecov_apache_reverse_proxy.conf on the host before compose up. Runtime Apache logs are written to /var/log/local/apache.

If you need a different runtime root, export APP_INSTALL_PATH before running container_install.sh. The compose file already mounts the Apache config from ${APP_INSTALL_PATH}.

Upgrade docker deployment

Use upgrade when DB schema/data already exist.

IMPORTANT:Before upgrading, perform backups from Backups.

cd relecov-platform
bash container_install.sh --engine podman \
  --action upgrade \
  --install_conf_map app,conf/docker_production_platform_settings.txt \
  --install_conf_map iskylims_app,../relecov-iskylims/conf/docker_production_iskylims_settings.txt \
  2>&1 | tee relecov_prod_upgrade.log

The upgrade path rebuilds/restarts the containers and runs install.sh --bootstrap upgrade inside each app container. The app files are already baked into the rebuilt images; the bootstrap phase applies migrations with --fake-initial, refreshes static files, and skips first-install setup.

Bare-metal deployment (Ubuntu/CentOS)

Install

Prepare DB/users/grants from Database creation, users and grants.
Edit config files:

relecov-platform/conf/install_settings.txt
relecov-iskylims/conf/install_settings.txt

Install dependencies + app (needs root):

cd relecov-platform
bash install.sh --install full --conf conf/install_settings.txt

cd ../relecov-iskylims
bash install.sh --install full --conf conf/install_settings.txt

The staged/bootstrap split added for container images is internal. Bare-metal commands do not change: --install and --upgrade still run the complete dependency, application, and database workflow shown here.

Upgrade

cd relecov-platform
bash install.sh --upgrade app --conf conf/install_settings.txt

cd ../relecov-iskylims
bash install.sh --upgrade app --conf conf/install_settings.txt

Before upgrading, perform backups from Backups.

Common operations (Docker + bare-metal)

Database creation, users and grants

Run as MySQL root:

CREATE DATABASE IF NOT EXISTS relecov_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS iskylims_rel_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE USER IF NOT EXISTS 'relecov'@'%' IDENTIFIED BY 'djangopass';
CREATE USER IF NOT EXISTS 'relecovlims'@'%' IDENTIFIED BY 'djangopass';

CREATE USER IF NOT EXISTS 'relecov'@'localhost' IDENTIFIED BY 'djangopass';
CREATE USER IF NOT EXISTS 'relecovlims'@'localhost' IDENTIFIED BY 'djangopass';

GRANT ALL PRIVILEGES ON relecov_dev.* TO 'relecov'@'%';
GRANT ALL PRIVILEGES ON relecov_dev.* TO 'relecov'@'localhost';

GRANT ALL PRIVILEGES ON iskylims_rel_dev.* TO 'relecovlims'@'%';
GRANT ALL PRIVILEGES ON iskylims_rel_dev.* TO 'relecovlims'@'localhost';

FLUSH PRIVILEGES;

Verification:

SHOW GRANTS FOR 'relecov'@'%';
SHOW GRANTS FOR 'relecovlims'@'%';

Backups

Database dumps:

mysqldump -h <db_host> -P <db_port> -u relecov -p relecov_dev > relecov_dev_$(date +%Y%m%d_%H%M%S).sql
mysqldump -h <db_host> -P <db_port> -u relecovlims -p iskylims_rel_dev > iskylims_rel_dev_$(date +%Y%m%d_%H%M%S).sql

RELECOV logs (host bind path used by production compose):

tar -czf relecov_logs_$(date +%Y%m%d_%H%M%S).tgz -C /var/log/local/apps/relecov-platform .

Docker/Podman named volumes (documents + nextstrain datasets):

# podman (replace with docker if needed)
podman run --rm -v relecov_documents:/from -v "$PWD":/to alpine \
  tar -czf /to/relecov_documents_$(date +%Y%m%d_%H%M%S).tgz -C /from .

podman run --rm -v nextstrain_data:/from -v "$PWD":/to alpine \
  tar -czf /to/nextstrain_data_$(date +%Y%m%d_%H%M%S).tgz -C /from .

Suggested backup order before any risky change:

DB dumps.
Documents volume.
Nextstrain datasets volume.
Logs archive.

Restore / rollback

Restore DB:

mysql -h <db_host> -P <db_port> -u relecov -p relecov_dev < relecov_dev_YYYYMMDD_HHMMSS.sql
mysql -h <db_host> -P <db_port> -u relecovlims -p iskylims_rel_dev < iskylims_rel_dev_YYYYMMDD_HHMMSS.sql

Restore volumes:

podman run --rm -v relecov_documents:/to -v "$PWD":/from alpine \
  sh -lc "cd /to && tar -xzf /from/relecov_documents_YYYYMMDD_HHMMSS.tgz"

podman run --rm -v nextstrain_data:/to -v "$PWD":/from alpine \
  sh -lc "cd /to && tar -xzf /from/nextstrain_data_YYYYMMDD_HHMMSS.tgz"

Restore logs archive:

sudo mkdir -p /var/log/local/apps/relecov-platform
sudo tar -xzf relecov_logs_YYYYMMDD_HHMMSS.tgz -C /var/log/local/apps/relecov-platform

What to do if something fails

Quick checks:

podman ps -a
podman logs --tail 200 relecov_app
podman logs --tail 200 relecov_iskylims_app
podman logs --tail 200 relecov_nextstrain

If deployment is broken after migration or bad data load, rollback using Restore / rollback.

Post-install configuration