Upgrading Central

We release new versions of Central regularly. We recommend that you upgrade as soon as you can to get access to the newest features, bug fixes, and security updates. It is not possible to downgrade and we do not guarantee that versions prior to the latest release can still be installed.

Start by reviewing upgrade notes for all versions between your current version and the one you are upgrading to. You will directly install the latest version but you must follow all upgrade instructions between your current version and the one you are upgrading to. If you are upgrading over many versions, the chance of error increases. We recommend first trying the upgrade on a clone of your production environment to validate the steps that you need to follow.

Upgrade notes

  • Central v2024.2: changes to .env and SSL no longer require rebuilding, consider using S3 storage

  • Central v2023.5, v2024.1: no upgrade notes

  • Central v2023.4: improve email delivery

  • Central v2023.3: clean up old database if needed

  • Central v2023.2: upgrade Docker, PostgreSQL, and move configuration to .env

  • Central v2023.1: plan ahead for longer than usual downtime during upgrade

  • Central v2022.3: update your NGINX configuration if you have disabled or customized Sentry

  • Central v1.5: fix errors with git pull if you have disabled or customized Sentry

  • Central v1.4: optionally add memory if you have tens of thousands of submissions

  • Central v1.3: ensure you have the correct version of docker-compose

  • Central v1.2: fix errors with git pull

  • Central v1.0, v1.1: no upgrade notes

  • Central v0.9: configure firewall

Note

To see your version, click on the question mark icon in the upper right section of your Central menu bar, then click Version. If you don't see the question mark, you can see the version by adding version.txt to the root URL (e.g., demo.getodk.cloud/version.txt).

Upgrade steps

Warning

Before starting:

  1. Back up your server.

  2. Make sure you have some time available in case something goes wrong (we recommend at least 2 hours). You may want to announce a maintenance window.

  3. Review upgrade instructions for all versions between your current version and the version you are upgrading to.

  1. Log into your server. If you used our DigitalOcean installation steps, we suggest reviewing the section Installing Central as a reminder, or if you can't remember your password to start at the top of that section to reset your password.

  2. Get the latest infrastructure version.

$ cd central
$ git pull

Note

If you have made local changes to the files, you may have to start with git stash, then run git stash pop after you perform the pull. If you aren't sure, run git pull and it will tell you.

  1. Get the latest client and server.

$ git submodule update -i

  1. Build from the latest code you just fetched. The pull option ensures all Docker images are up-to-date.

$ docker compose pull && docker compose build --pull

Note

If you run into problems with this step, try stopping Central (docker compose stop) and then retry docker compose build --pull.

  1. Clean up unused Docker images

$ docker image prune

You'll be asked to confirm the removal of all dangling images. Agree by typing the letter y and pressing Enter.

Note

For a more thorough, but potentially dangerous clean up, consider using docker system prune.

  1. Restart the server

$ docker compose stop && docker compose up -d

Version-specific upgrade instructions

Upgrading to Central v2024.2

There are no required special steps related to this upgrade. However, there are some optional changes that you may want to know about or opt into.

1. Changes to .env and SSL no longer require rebuilding

If you make changes to your .env file or your SSL certificates to configure Central as described in the setup and configuration instructions, you no longer have to rebuild Central for the changes to take effect. Instead, a stop and restart is now enough:

$ docker compose stop
$ docker compose up -d

2. Files can be stored in S3-compatible storage

By default, Central stores all of its data in a database, including files like XLSForm definitions and images attached to submissions. If you have or plan on collecting a lot of files, you may prefer to store these in separate storage to reduce load on the database and possibly reduce hosting costs. See instructions on configuring S3-compatible storage.

3. Docker images now published

If you use your own infrastructure for orchestrating the different components needed to run Central, you may prefer to use published Docker images. You can now find these on GHCR.

Upgrading to Central v2023.4

  1. Determine whether the install you are upgrading is using a custom mail server or the default one:

    $ grep EMAIL_HOST .env

    If you get nothing back or there's nothing after the =, you are using the default mail server. If DB_HOST is set to any value, you are using a custom mail server.

  2. Upgrade your install according to your mail server type.

Tip

While enabling DKIM on the default mail server will improve email delivery, we strongly recommend you use a custom mail server instead.

  1. Copy any existing DKIM files to a new location.

    $ cd central

    $ mkdir files/mail
$ test -f files/dkim/rsa.private && cp files/dkim/rsa.private files/mail/rsa.private

  2. Delete the old DKIM folder and its contents.

    $ rm -r files/dkim

  3. Follow the standard upgrade instructions. Be sure to return here after the upgrade.

  4. Follow the configure DKIM instructions to further improve email delivery. Redo these instructions even if you have previously configured DKIM.

Upgrading to Central v2023.3

  1. Determine which version of Central you are running. To see your version, click on the question mark icon in the upper right section of your Central menu bar, then click Version. If you don't see the question mark, you can see the version by adding version.txt to the root URL (e.g., demo.getodk.cloud/version.txt).

  2. Select the tab below that matches the version of Central you are running.

If you are running a version older than v2023.2, follow the Central v2023.2 instructions. After following those instructions, you will be running v2023.3. No further action will be needed.

Upgrading to Central v2023.2

This is critical infrastructure upgrade. In particular, it upgrades the included PostgreSQL database from 9.6 (no longer supported) to 14 (stable and supported through 2026). Docker and Docker Compose are also upgraded. This release also changes the way that configurations are made to reduce conflicts with future updates to Central. Please read the following instructions carefully.

Warning

This upgrade may take more time and disk space than previous updates.

Warning

Before starting:

  1. Back up your server.

  2. Make sure you have some time available in case something goes wrong (we recommend at least 3 hours). You may want to announce a maintenance window.

  3. Review upgrade notes for all versions between your current version and the version you are upgrading to.

  1. Log into the web interface and make a quick note of some of the data you see, such as submission counts and latest submission dates. You may want to use this information to do a quick spot check after the upgrade is finished.

  2. Log into your server. If you used our DigitalOcean installation steps, we suggest reviewing the section Installing Central as a reminder, or if you can't remember your password to start at the top of that section to reset your password.

  3. Go to the central folder.

    $ cd central

  4. Upgrade Docker if needed. Check to see if you have Docker Engine v23.x and Docker Compose v2.16.x or greater:

    $ docker --version && docker compose version

    If you are using old versions, follow the instructions to install Docker Engine (not Desktop) for Ubuntu, the operating system we recommend and support. The instructions will help you setup the Docker apt repository and install the latest version of Docker Engine and Docker Compose.

  5. Remove docker-compose. You will be using docker compose from now on (the dash has been replaced with a space).

    $ rm -f `which docker-compose`

  6. Migrate configuration customizations. This will simplify future Central upgrades. First, check what files have been customized:

    $ git status

    If you do not see any files listed with a modified: prefix, you can go on to the next step.

    If you see files listed with a modified: prefix, follow instructions for each of them:

    files/service/config.json.template

    1. Make a backup copy of the file. You will manually copy differences to your local computer later so this is for additional protection:

      $ cp files/service/config.json.template files/service/config.json.template.bak

    2. Copy changes to your local computer:

      $ git diff files/service/config.json.template

      You will see additions in green with + prefixes. Copy those to a scratch file on your local computer (e.g. using CTRL+C and CTRL+V). You will use this to copy your custom values into the new format.

    3. Open the .env file for editing:

      $ nano .env

    4. If you use a custom database server, you will see changes in the database section. Copy the values from that section to the .env file in the following format:

      DB_HOST=my-db-host
DB_USER=my-db-user
DB_PASSWORD=my-db-password
DB_NAME=my-db-name

      Note

      If your password has special characters in it, you will need to put single quotes ( ' and ') around the password. Values without special characters do not need quotes around them.

      Note

      If your database requires an SSL connection, add DB_SSL=true to .env. If you don't need an SSL connection, omit that variable. Note that DB_SSL=true allows self-signed certificates.

    5. If you use a custom email server, you will see changes in the email section. Copy those values to the .env file in the following format:

      EMAIL_FROM=my-no-reply-email-address
EMAIL_HOST=my-email-host
EMAIL_PORT=my-email-port
EMAIL_IGNORE_TLS=true-or-false
EMAIL_SECURE=true-or-false
EMAIL_USER=my-email-user
EMAIL_PASSWORD=my-email-password

      Note

      EMAIL_IGNORE_TLS should generally be set to false. EMAIL_SECURE should be set to true if you use port 465 and to false for other ports.

      Note

      If your password has special characters in it, you will need to put single quotes ( ' and ') around the password. Values without special characters do not need quotes around them.

      Note

      EMAIL_FROM is equivalent to email.serviceAccount in the json config. If you omit it, the default is no-reply@${YOUR_DOMAIN}. You can specify a name that will be shown by email clients by using the following structure:

      EMAIL_FROM=My Cool Server <no-reply@my-server.server>

    6. Discard all files/service/config.json.template customizations. Make sure you have correctly copied all of them into .env. You may want to keep the copy on your local computer until you have verified that everything works.

      $ git checkout -- files/service/config.json.template
    docker-compose.yml

    1. Make a backup copy of the file. You will manually copy differences to your local computer later so this is for additional protection:

      $ cp docker-compose.yml docker-compose.yml.bak

    2. Copy changes to your local computer:

      $ git diff docker-compose.yml

      You will see additions in green with + prefixes.

      You can ignore any changes related to a custom database because those have been addressed by migrating files/service/config.json.template.

      Copy any other changes to a scratch file on your local computer (e.g. using CTRL+C and CTRL+V). You will use this to copy your custom values into the new format.

    3. If you specify a value for SERVICE_NODE_OPTIONS, open the .env file for editing:

      $ nano .env

      Copy that to the .env file in the following format:

      SERVICE_NODE_OPTIONS=my-node-options

    4. If you specify any other customizations in your docker-compose.yml file, this is considered advanced and you will need to apply them manually after the upgrade. If you're not sure how to do this, write a support post on the forum.

    5. Discard all docker-compose.yml customizations. Make sure you have correctly copied all of them into .env. You may want to keep the copy on your local computer until you have verified that everything works.

      $ git checkout -- docker-compose.yml
    files/enketo/config.json.template or any others

    1. Stash changes so they can be applied after the upgrade. These are considered advanced customizations and you may need to resolve merge conflicts when you re-apply them.

      $ git stash

  7. Determine whether the server you are upgrading is using a custom database (e.g. externally hosted on Azure, AWS, etc.) or the default one:

    grep DB_HOST .env

    If you get nothing back or there's nothing after the =, you are using the default database. If DB_HOST is set to any value, you are using a custom database server.

  8. Upgrade your database according to your database type.

    Warning

    Before starting, read the instructions at the top of this section carefully and make sure you are actually using the default database configuration. Following these instructions with a custom database setup could result in perceived data loss.

    1. Get the latest infrastructure version.

      $ git pull

    2. Get the latest client and server.

      $ git submodule update -i

    3. Check that you have enough disk space available. If you are prompted for a password, enter the system superuser password (not a Central password). You will see a message about how much space is required and if you have enough free space to proceed.

      $ sudo ./files/postgres14/upgrade/check-available-space

      If you don't have enough space, stop here and resume when you have increased the disk space available. You may achieve this by clearing out data you don't need (e.g., logs) or by increasing the total disk space available.

    4. Create a file to prove that you're carefully reading these instructions. This is required to continue.

      $ touch ./files/allow-postgres14-upgrade

    5. Reapply any advanced customizations. If you had made notes on advanced configurations and/or stashed some edited files, reapply those advanced customizations now:

      $ git stash pop

    6. Build from the latest code you just fetched.

      $ docker compose pull
$ docker compose build --pull

    7. Start the database upgrade and wait for the process to exit. This is where the new PostgreSQL 14 database is made and data copied into it. This will take a long time if you have a lot of data and/or a slow server.

      $ docker compose up postgres

    8. Check the output of the previous command to see if there were any errors. If there were any errors that you can't resolve, write a support post on the forum.

    9. Check the upgrade success file has been created.

      $ ls ./files/postgres14/upgrade/upgrade-successful

      If you see "No such file or directory," try doing docker compose up postgres again. If the file has still not been created, write a support post on the forum.

    10. Restart the server.

      $ docker compose up -d

    11. Log into the web interface and do some quick spot checks. For example, verify that submission counts and latest submission dates look right and try a data export.

    12. Clean up

      1. Remove unused Docker images.

        $ docker image prune

        You'll be asked to confirm the removal of all dangling images. Agree by typing y and pressing Enter.

      2. See how much space the old database takes. The upgrade process performs a copy and leaves the old database intact.

        $ docker compose up postgres

      3. Delete the old data. Make sure you have verified that the server works as expected first.

        $ touch ./files/postgres14/upgrade/delete-old-data \
   && docker compose up --abort-on-container-exit postgres

Upgrading to Central v2023.1

There are several time-consuming steps in this upgrade. Central will not be accessible during those steps. Plan for a minimum of an hour of downtime.

If you have 30K or more submissions, consider temporarily increasing server performance and memory allocation before upgrading.

If you have 20K or more versions of a single form (generally generated by an automated script that uses the API to update a form attachment), email support@getodk.org with details about your infrastructure and the number of form versions you have before starting the upgrade process so we can help you plan for a successful upgrade.

Upgrading to Central v2022.3

In v2022.3, we added Content Security Policy reporting. If you have disabled or customized Sentry, then you will need to modify files/nginx/odk.conf.template. See our documentation about configuring Sentry to learn more about the specific changes that you need to make.

Upgrading to Central v1.5

In v1.5.3, we updated Central's Sentry configuration to match a change to the Sentry API. If you have not changed your Sentry configuration, then you do not need to do anything special.

If you have changed your Sentry configuration, that means that you have modified files/service/config.json.template. If you run the git pull command, then you will see an error message like the following:

error: Your local changes to the following files would be overwritten by merge:
        files/service/config.json.template
Please commit your changes or stash them before you merge.

Don't worry, nothing bad happens if you see this. To get around this error, run this set of commands instead of git pull:

mv files/service/config.json.template config-tmp
git pull
mv config-tmp files/service/config.json.template

If you see an error message when you run this set of commands, copy and paste your entire console session into a forum thread and someone will help you out.

If you are using your own Sentry instance, then you must complete one additional step. You will need to modify files/service/config.json.template. Below the line that contains "sentry": {, insert a new line that looks like this:

"orgSubdomain": "SENTRY_ORGANIZATION_SUBDOMAIN",

Replace SENTRY_ORGANIZATION_SUBDOMAIN with your Sentry organization subdomain.

Upgrading to Central v1.4

There are several time-consuming migrations in v1.4. If you have tens of thousands of submissions, consider temporarily increasing server performance and memory allocation before upgrading.

Upgrading to Central v1.3

Before upgrading, run docker-compose --version to confirm you have docker-compose v1.28.3 or later. If you don't, upgrade with these commands from Docker's documentation.

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Upgrading to Central v1.2

In v1.2, we added some advanced features to Central's server configuration. These features will not be meaningful to most users. However, because we would like to make this change and further improvements in the future, we have modified the template .env configuration file you set up during installation.

Since you have made your own changes to the .env file to set Central up for your environment, you will see an error message when you run the git pull command:

error: Your local changes to the following files would be overwritten by merge:
        .env
Please commit your changes or stash them before you merge.

Don't worry, nothing bad happens if you see this. To get around this error, run this set of commands instead of git pull:

mv .env env-tmp
git pull
mv env-tmp .env

Afterwards, git status should not say anything about the .env file at all and you can continue with the upgrade instructions above.

If git status still shows errors, copy and paste your entire console session into a forum thread and someone will help you out.

Upgrading to Central v0.9

Particularly if you are installed on DigitalOcean, you will need to modify the system firewall for Enketo features in Central to work correctly.

The quickest way to do this is to run ufw disable while logged into your server's command line prompt. You should see the message Firewall stopped and disabled on system startup. If so, you have configured the firewall correctly.

For advanced administrators

While it sounds dangerous, disabling your system firewall does not put your server at greater risk. In fact, most Linux operating systems come with the system firewall disabled.

If you don't want to disable the firewall entirely, you can instead configure Docker, iptables, and ufw yourself. This can be really difficult to do correctly, so we don't recommend most people try. Another option is to use an upstream network firewall.

The goal here is to ensure that it is possible to access the host through its external IP from within each Docker container. In particular, if you can successfully curl your Central website over HTTPS on its public domain name from within the Enketo container, all Enketo features should work correctly.

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No