How to Update Specify 7

SCC Governance Policies
1

[!note] Before You Begin
Consider that the Specify Collections Consortium (SCC) offers the Specify Cloud hosting service to members of the consortium.

By choosing SCC’s Specify Cloud hosting, you get a fully managed Specify 7 environment with automatic updates, priority support, and low-latency servers in cloud regions around the world. Daily backups of your database and attachments ensure your data is always protected. If you’d like pricing details, please see our services prices or get in touch at membership@specifysoftware.org.

This guide outlines the standard procedure for updating a self-hosted Specify 7 deployment to the latest version. Following these steps will ensure a smooth transition while safeguarding your data.

Understanding Docker Release Tags

For production deployments, the SCC recommends using the v7 Docker tag, as it always points to the latest stable, tagged release of Specify 7. If you prefer to remain on a specific point release, you can use a more specific tag. The database itself will be updated automatically when the Specify 7 container starts for the first time after an update.

Tag Pulls
v7 The latest stable, tagged release of Specify 7. (Recommended)
v7.x The latest release within the major version 7.x (e.g., v7.10.2).
v7.x.x A specific point release (e.g., v7.10.1).

The Update Process

Follow these steps to safely upgrade your self-hosted system.

Step 1: Review the Release Notes

Before starting an update, always check the Specify Discourse for release announcements. Pay close attention to any breaking changes, new environment variables, or notes on database migrations that might affect your configuration.

Step 2: Back Up Your Data

Since the update process may perform database migrations to modify tables and add new records, performing a full backup is a critical first step.

  1. Back Up the Database:
    If using MariaDB in Docker, use docker exec to run mysqldump inside your database container and create a backup of your Specify database.

    docker exec <db_container_name> \
  mysqldump -u root -p"${MYSQL_ROOT_PASSWORD}" \
  --databases "${MYSQL_DATABASE}" > ${MYSQL_DATABASE}_backup.sql

    If MariaDB is on a different server or installed locally, you can execute:

    mariadbdump \
  --host=DB_HOST \
  --port=DB_PORT \
  --user=DB_USER \
  --password \
  --single-transaction \
  --quick \
  SPECIFY_DATABASE_NAME \
  > ${MYSQL_DATABASE}_backup.sql

    After pressing Enter you’ll be prompted for your database password. The resulting databasename_backup.sql is a plain-text dump of your entire database.

[!warning] Rolling Back?
If a roll back to a previous database backup is necessary, you must drop and recreate the database entirely. Restoring a previous backup directly over an existing database will not remove the new tables created by the update, likely resulting in migration errors due to existing tables/fields when Specify attempts to create those once again.

Step 3: Update Docker Compose Configuration

Next, update your local configuration to use the new software versions.

  1. Pull the Latest Images:

    docker compose pull

  2. Update Image Tags:
    In your docker-compose.yml file, ensure the service images point to the desired release tag. We recommend using v7 to always get the latest stable release.

    services:
  specify7:
    image: specifyconsortium/specify7-service:v7
  specify7-worker:
    image: specifyconsortium/report-runner:v7

  3. Merge Configuration Changes:
    Compare your docker-compose.yml and nginx.conf files with the latest examples in the specify/docker-compositions repository. Add or update any new environment variables or Nginx proxy rules as noted in the release announcement.

Step 4: Relaunch and Verify :white_check_mark:

With your configurations updated and backups secured, you can now perform the upgrade.

  1. Stop the Current Services:

    docker compose down --remove-orphans

  2. Ensure Elevated Credentials for Migrations:
    When running Specify 7 for the first time or during updates that require migrations, set MASTER_NAME and MASTER_PASSWORD to the root username and password of your database. This step is crucial for executing Django migrations during the initial setup or upgrade. After launching Specify and confirming that the update is complete, you can safely replace these credentials with your regular master SQL username and password.

  3. Start the New Services and Apply Migrations:
    When the specify7 container starts, it automatically runs any necessary database migrations. Ensure your .env file or docker-compose.yml is configured with the elevated credentials defined above.

    docker compose up -d

  4. Monitor the Logs:

    docker compose logs -f specify7 nginx

    Look for output from the specify7 container indicating that database migrations are running and completing successfully.

  5. Verify Functionality:
    Once the containers are running, log in to the Specify 7 web interface and test key functionality:

    • Perform a record search.
    • Open and save a record.
    • Upload or view an attachment.
    • Generate a label or report (if the report runner is in use).

Step 5: Clean Up Old Images (Optional)

After confirming that the new version is running correctly, you can remove old, unused Docker images to free up disk space.

docker image prune -f

Best Practices

• Test in a Staging Environment: Whenever possible, test the upgrade process on a staging server with a recent copy of your production data before updating your live instance.
• Use Elevated Credentials for Updates: Always ensure the DATABASE_HOST, DATABASE_NAME, MASTER_NAME, and MASTER_PASSWORD environment variables point to a user with sufficient privileges (like root) to perform database schema changes during migrations. You can switch back to less-privileged credentials for daily operations afterward.
• Secure Your Production Environment: For live deployments, ensure debug modes are turned off (SP7_DEBUG=false) and that you have configured HTTPS at your Nginx proxy layer.