Upgrading a Dockerized Yarkon Server

Docker makes upgrading software safe and simple, but you do need to take care to ensure you are not overriding existing data.

This guide demonstrates the process using docker-compose, but it should be similar using other orchestration platforms.

The basic configuration file

Take a close look at the recommended docker-compose.yml file, which is used as a reference for all following discussions:

version: "3.2"

    # We use "xyz" to denote the version number used. For instance, if you are using
    # yarkon version 4.5.1, "xyz" would be "451". You can use another naming convention
    # if you prefer. Explicitely definding the version number in the image tag and
    # volumes ensures that upgrades can be done sequentially and you can always restore
    # to a previous version.

services:
  server:
    image: "yarkon/server:x.y.z"  # Use the correct tag here
    ports:
      # Map the port of the host to the one used by Yarkon
      - "80:8000"
    environment:
      # When running in AWS, the preferred way to provide AWS API keys to the
      # container is through using an IAM machine role. If this cannot be done,
      # or when running it outside of AWS, you can pass credentials here:
      AWS_ACCESS_KEY_ID: "EXAMPLERFP4S3EXAMPLE"
      AWS_SECRET_ACCESS_KEY: "examplexcRA2gvPBPKAmt95yWIwz/vJIJexample"
      AWS_REGION: "us-east-1"

      # The provider name defaults to AWS, but you can change it to something
      # your users might find more recognizable. In the client, it is displayed
      # above the buckets and in the About form.
      PROVIDER_NAME: "My Company"

    volumes:
      - dbdata_xyz:/var/app/current/database
      - yarkon_xyz:/var/app/current/public/yarkon
      - license:/var/app/current/.lic
      - /var/log:/var/app/current/log # Map the /var/log folder on the host to the log folder
volumes:
  dbdata_xyz:
  yarkon_xyz:
  license:

We strongly recommend that all upgrades would be done explicitly, so that you have full control over the version of the application and the database, and would always be able to revert to an older version if there is a need.

To that end, we recommend that you'd explicitly reference the version number when referencing the image and the mounted volumes. In our sample file, we use the common naming convention "xyz" to refer to a version. For instance, Yarkon version 4.5.1 would be referenced as "451" and so forth.

Understanding the image tag

The image tag defines which version of the application is used when a docker container starts. The dockerized version of Yarkon Server is publically available from Docker Hub, and the notation used in the docker-compose file instructs docker to download the correct version from the public repository. For instance, specifying yarkon/server:451 will use version 4.5.1.

Note that you can replace the version number with the latest tag, but we discourage that approach in a production environment, as it might result in a newer version being used inadvertently in case you restart a container after we made an upgrade in Docker Hub.

Understanding the volumes tag

The volumes tag tells docker where to find folders that are mapped on the host. This is the recommended approach to ensure that data is persisted between container restarts. Examples for files you definitely want persisted:

  1. The database.
  2. The custom theme you use for branding.

The database is located in /var/app/current/database. The custom theme is located in /var/app/current/public/yarkon.

You can use either the approach we use in the sample file here, which results in docker creating the mounting points, or define the path on the host (like we show in the sample file for the logs). Either approach is fine.

Upgrading to a new version

A proper software version upgrade takes care of the following:

  1. Upgrading the software to a new version.
  2. Migrating the database schema to match the new version.
  3. Updating the assets used by the application (the client side HTML etc).

We strongly recommend that you will perform any upgrade first using a local set up - in a non production environment. This is to ensure that you are familiar with all the steps involved and there are no surprises when you handle the production deployment.

Preparing for the software

Once a new release is available from Docker Hub, identify the release number, and update the config file appropriately. For instance, if you were using Yarkon Server version 4.5.1, your image tag should read yarkon/server:451. Let's say that you want to upgrade to a newer version labeled 5.0.0 - update your image tag to yarkon/server:500 and restart the docker-compose. The new version would be pulled from the registry and used.

Preparing for the database

A new version of Yarkon Server will automatically handle database migration (meaning, upgrading the database schema to a newer version), and will keep backups of the older version. This is called an "in-place" upgrade. However, we believe that in most cases it is preferable to not do an "in-place" upgrade, and instead handle the upgrade manually - the process is simple and doing it manually allows for better control and ensure that backups are readily available. This is referred to as a "side-by-side" upgrade. In the rest of this guide, we proceed with a "side-by-side" upgrade.

Just like we did for the image tag, update the volume referencing the database based on its version number. Note that unlike the Docker Hub reference, this naming is actually arbitrary, but we do recommend you'd keep it consistent with the image tag. As was mentioned before, you can use the docker mounting option, as we do in the sample file, or explicitly define mounting points on the host. The end result is similar, as far as the application is concerned.

If you prefer to do an "in-place" update of the database, do not use the version number in the volume name. That way, the database file will be updated (replaced) as was aforementioned.

Preparing for the assets

Same as we did for the database, update the volume for the assets. The assets include all content that is served to end users, such as HTML, Javascript, CSS and also any branding changes you made.

Upgrading

Once you are done with the configuration changes, you are ready for the upgrade itself.

Backup the database

To make the process easier, take a backup of the database using the Adminstration section, Database tab. Doing so will download the latest database file to your PC, making it easier for you to handle the restore without needed to do file copies into the container.

Restart the container

This step depends on the orchestration system you use. In the simple case of docker-compose we use here, we simply stop the container and bring it up again using docker-compose up.

When the container starts, it will go into the set up step. This is the expected behavior, since we are not doing an "in-place" update of the database. Put in the same details as you did before. They will be updated once the database is migrated over, but better to keep things the same if possible.

Restore the database

Go back to the same screen you used to backup the database, and using the local copy you just created, do a database restore. The application should now handle the migration of the schema to match the new version, and when done, will prompt you for your login credentials. These would be the credentials you used when you backed up the database (thus overriding the new setup, in case you used different credentials).

At this point, you have a fully operational server, running the new version. You can verify that by checking the version numbers in the Overview page. Also open the client application, and using the Help|About form, verify that a new version is being used.

About the license file

If you follow the sample here, then the license file need not be updated during a migration. This is because we use the sample volume for the license key file. If for whatever reason you want to update it, you can use the same tagging naming convention for the license volume, and then re-upload the file when the new version of the application is running.