Upgrading 4CAT

If you have already installed 4CAT and want to upgrade to the latest release, you can use the following methods. If you are a system administrator managing a 4CAT server with many users or on a remote server, you may want to also read the additional notes.

Upgrading via the web interface

1. Log in with an admin account
2. Navigate to the 'Control Panel' via the navigation bar at the top of the interface
3. Click the 'Restart or Upgrade' button at the top
4. If a new version is available, click the 'Upgrade' button. Make sure to carefully read the instructions on the page first.

Upgrading with Docker Desktop

If upgrading via the web interface fails, and you're using Docker Desktop to run 4CAT, the following alternative method can be used to upgrade to the latest 4CAT release unless otherwise noted in the release notes:

1. In the Docker Desktop sidebar, click 'Images' to open the list of downloaded Docker images
2. Look for the 'digitalmethodsinitiative/4cat' image in the list. Click the three dots under 'actions' and choose 'Pull' to download the latest version of the image. Once you see the 'Status: Image is up to date for digitalmethodsinitiative/4cat:stable' notice pop up, the image has been upgraded to the latest version.
   

   

   
   
3. Open a terminal and navigate to the location of your 'docker-compose.yml' file. If you're unsure where this is, click the '4cat' container name in Docker Desktop. The file path is noted at the top of the details screen that opens.
   

   

   
   For example, to navigate to the path listed above, use the following terminal command:

   cd /Users/stijn/PycharmProjects/4cat
   

4. Run the following command:

   docker compose down && docker compose up --detach
   

5. Wait until the command completes. Once it does, 4CAT will have restarted with the latest version of the software; you can close the terminal window and resume using 4CAT via the web interface.

Upgrading with Docker via the command line

If you are running 4CAT via Docker but not using Docker Desktop, you can upgrade the following way:

1. Open a terminal and navigate to the folder in which the docker-compose.yml file you used to build the containers is located
2. Remove the existing containers

• docker compose down

3. Download the docker-compose.yml and the .env files associated with your desired version.

• You can find these in the .zip file you download via the releases page or .env here and docker-compose.yml here.
• Edit the .env as necessary (compare with settings from your old .env file); please ensure the Docker Volume names correspond with your previous installation to ensure the installation uses your previous data (this is the likeliest disconnect to verify if you do not have access to your data after upgrading; identify the correct name in Docker and repeat these steps)

4. Download the latest 4CAT image

• docker compose pull (Docker will download the version designated in the .env file set as DOCKER_TAG)

5. Redeploy the containers

• docker compose up -d

See Additional Notes for more information, such as Postgres database versions.

Upgrading a manual installation via the command line

1. Open a terminal and navigate to the folder 4CAT is running from
2. (Optionally) activate the virtual environment
3. Run python3 helper-scripts/migrate.py --release --restart and follow the instructions

Optionally, you can run the latest development version (i.e. the master branch of this repository) by running python3 helper-scripts/migrate.py --branch master --restart. Note that this is UNSUPPORTED and that this branch may contain more bugs than the regular releases.

Additional notes

Docker installations

In Docker, the 4CAT web interface upgrade feature modifies both the volume data (which persists) and the container itself (which persists when stopping and starting containers, but NOT when building or redeploying from an existing 4CAT image). You will thus notice no difference if you keep the existing Docker container and stop and start it as needed. However, if you run 4CAT from the a Docker image, you may experience slowdowns after upgrading. When deploying with an older existing image, 4CAT will read the persistent volume information and upgrade the containers again to the current version. Depending on your setup, it may be faster/more efficient to download the most recent 4CAT image and deploy using that image. I.e., to follow the command line instructions on updating 4CAT.

Note: Early Docker V1 used the docker-compose command, but V2 version use docker compose. There are differences between the two commands, but they should not effect the following commands to upgrade 4CAT. I.e., older Docker versions can replace docker compose with docker-compose.

Postgres Versions

When upgrading 4CAT it is possible that your database is from a previous version of Postgres that is incompatible with their latest Docker image. You may see a message when redeploying 4CAT similar to The data directory was initialized by PostgreSQL version 14, which is not compatible with this version 15.3 (Debian 15.3-1.pgdg120+1). In that case, you can either follow postgres's instructions to update your database or edit the .env file to continue using the older database version (i.e., edit POSTGRES_TAG to the corresponding version, 14 in this case).

Upgrading older 4CAT Versions

Docker 4CAT releases v1.30 to v1.33

An issue was identified that caused the interactive upgrade process to fail in our Docker setup (a GitHub update in the Docker image build process causes 4CAT to not be able to update its own code). In order to upgrade any of these versions, you must upgrade via the command line instructions. The issue was fixed in v1.34.

Docker PRIOR to v1.26

v1.26 migrated configuration settings from config.py to the database. Docker will lose those settings if you rebuild the image. If you never changed config.py, you can update per the instructions above. You may want to copy config.py from your 4CAT container prior to recreating it via docker cp 4cat_backend:/usr/src/app/config.py ./ in case there are issues migrating. A migrate script was developed to move your config.py settings to the new database (where they will be permanent and editable via the 4CAT web interface).

1. Update the 4cat_backend
   • docker exec -it 4cat_backend /bin/bash
   • git pull
   • optionally: git checkout COMMIT_ID or git checkout BRANCH_NAME
   • python3 4cat-daemon.py stop
   • python3 helper-scripts/migrate.py
2. Update the 4cat_frontend
   • docker exec -it 4cat_backend /bin/bash
   • git pull
   • optionally: git checkout COMMIT_ID or git checkout BRANCH_NAME
   • python3 helper-scripts/migrate.py
3. Restart the containers
   • cd your/4cat/directory/
   • docker-compose stop
   • docker-compose start

Known Issues

The helper-scripts/migrate.py script works based on a .current-version file that is created in the main 4CAT directory. This file is not maintained by Docker and is lost on rebuild. Normally this does not matter as Docker creates the environment itself, however, it is possible that necessary changes do not take place (particularly with the database). You can force migrate to run by deleting the .current-version file and running helper-scripts/mirgate.py. E.g.: - docker exec -it 4cat_backend /bin/bash - python3 4cat-daemon.py stop - rm .current-version - python3 helper-scripts/migrate.py - python3 4cat-daemon.py start

How to open a Terminal

On Windows:

• Open the 'Command Prompt' or 'Terminal' application that comes with Windows; both work for our purposes.

On macOS:

• Open the 'Terminal' application that comes with macOS.

On Linux:

• Linux comes in many shapes and sizes. Look for an application with 'Prompt', 'Terminal', or 'Shell' in its name.