[ACTION REQUIRED] Upcoming Deprecation of older docker images and static JS/CSS assets

[sjahl]

What is happening?

Summary

Seqr is making updates to how our docker images work, and you will need to update your deployment by 2022/04/04. Please see the information below for more details.

Slightly Longer Version

We’re making two functional changes to the way seqr is packaged in Docker.

1. We will be removing the statically built javascript/CSS/HTML assets that are checked into git. These will now be generated in the docker image when it’s built, rather than provided in the source code tree.
2. New docker images will be built every time we release seqr. These images will no longer git pull to update themselves on startup.

However, if you are using a docker image from prior to when we made these changes, your installation still has the git pull update functionality. If you do nothing, your seqr installation may break after 2022/04/04 when it pulls down the version of the seqr code that has the assets removed. You will find instructions below on how to proceed.

Going forward, we will be publishing new versions of the seqr docker image every time we release seqr. Updating your seqr installation will now involve periodically pulling the new docker image and then restarting the container.

What Should I do?

If you run a local installation of seqr using our docker-compose.yml file and the official gcr.io/seqr-project/seqr docker images

Before proceeding: There is a chance that your docker image has accumulated state in the /seqr_static_media/generated_files directory inside your container. You should copy the files in that directory out of the seqr container before redeploying, or the files will be deleted. With the updated container, that directory will now be a volume like the other data folders in the docker-compose file. You can copy data into the volume mount in your data folder after you update your seqr installation, and the data will be persisted there.

Before 2022/04/04, you need to:

1. Download a new version of the docker-compose.yml file as described in the local install documentation
2. Pull updated docker images with the “docker-compose pull” command
3. Restart seqr with the “docker-compose up -d seqr” command

After this is complete: From now on, you will use this docker-compose pull/up sequence to update your seqr installation. It will no longer update itself in the event that your container restarts.

If you build your own version of the seqr docker image using the Dockerfile from the seqr repository

The following changes may impact how you build your container:

• As noted above, the container’s entry point script no longer runs git pull on container startup. To update seqr, you will need to build and deploy a new version of your docker container
• The Dockerfile no longer accepts the SEQR_REPO and SEQR_BRANCH build ARGs
  • The build now copies whichever repository and branch you have checked out locally. To use a specific repository or branch in the container, simply git checkout that repo/branch, and then run your docker build (or configure your build automation tool to do this)
• The build will use NPM to compile the static HTML, Javascript, and CSS assets each time you build the container
• These files will no longer be checked into the git tree at ui/dist or static/, and are generated dynamically for the code contained in the docker image

Why are we doing this?

Currently seqr publishes a docker image that changes infrequently. The way you typically get updates to seqr is through a git pull that the container runs:

• Each time it starts up
• When it is restarted
• By an administrator manually running git pull inside the seqr container

While this is sometimes convenient because you don’t have to pull new docker images, it’s also problematic for a few reasons:

• Having a seqr codebase that updates without the rest of the image makes the docker image “mutable”:

  • It means that updating seqr is a different process than updating most applications that run in docker-compose or Kubernetes.
  • It makes it possible to run a very old docker image with a very recent version of seqr. New versions of seqr may not necessarily be compatible with that old docker image (python and/or operating system version differences, etc), and break when you update it.
  • Security updates to the underlying operating system in your seqr image are not deployed in a timely manner.
  • Seqr can update itself without your awareness, which can cause problems if you weren’t expecting it. For example, this often causes errors when the seqr database schema has been updated.
  • It’s not conducive to automatically building the docker image with specific versions of seqr.

• The seqr project also publishes statically built HTML, CSS, and Javascript assets in its git repository. This is problematic because:

  • The static assets are generally only good for running the upstream master branch of seqr; they won’t work if you make local modifications to your UI code.
  • Checking the statically built assets into git creates unnecessary churn and duplication in the git repository, and requires a manual step before each seqr release

The end result is an image and dockerfile that are more amenable to automated builds, align more closely with typical docker-compose/kubernetes deployment patterns, and that provide more flexibility in building alternate or customized versions of seqr.

If you have questions or concerns about this change, please don't hesitate to respond here!