Skip to content

Upgrading 4CAT

Jump to bottom
Dale Wahl edited this page Jul 5, 2023 · 36 revisions

If you have already installed 4CAT and want to upgrade to the latest release, you can use the following methods:

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.

Note on Docker instances

The above method works on Docker instances, however may cause some slow downs if your deployment strategy involves frequently redeploying 4CAT from the Docker image. System admins may wish to read these additional notes.

Upgrading via the command line

Docker - how to upgrade with command

  1. 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
  1. 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)
  1. Download the latest 4CAT image
  • docker-compose pull (Docker will download the version designated in the .env file set as DOCKER_TAG)
  1. Redeploy the containers
  • docker-compose up -d

Manual installation - how to upgrade with command

  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

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.

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.

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

🐈🐈🐈🐈

Clone this wiki locally