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 (Recommended) The latest stable, tagged release of Specify 7.
v7.x The latest release within the major version 7.x (e.g., v7.10 would pull v7.10.2 but not v7.11.0).
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 use execute one of these commands, replacing DB_HOST, DB_PORT, DB_USER, and SPECIFY_DATABASE_NAME with the appropriate values:

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.

Step 3: Update Docker Compose Configuration

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

1. Pull the Latest Images:
Fetch the latest images from Docker Hub that are referenced in your docker-compose.yml file.

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:
Bring down your running containers. The --remove-orphans flag is useful for cleaning up containers from services that may have been removed from the compose file.

docker compose down --remove-orphans

2. Start the New Services and Apply Migrations:
When the specify7 container starts, it automatically runs any necessary database migrations. It is crucial to use the IT user credentials (often the root user for the database container) for this step, not the Master user, as migrations require elevated permissions to alter the database schema. Ensure your .env file or docker-compose.yml is configured with these credentials.

Start the services in detached mode:

docker compose up -d

3. Monitor the Logs:
Watch the container logs to ensure all services start correctly and that the database migrations complete without errors.

docker compose logs -f specify7 nginx

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

4. Verify Functionality:
Once the containers are running, log in to the Specify 7 web interface and test key functionality to confirm the upgrade was successful:

  • 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 you have confirmed 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 the IT User for Updates: Always ensure the DATABASE_HOST, DATABASE_NAME, MASTER_NAME, and MASTER_PASSWORD variables in your environment 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 if desired.
  • 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.