-
Notifications
You must be signed in to change notification settings - Fork 59
Upgrading 4CAT
If you have already installed 4CAT and want to upgrade to the latest release, you can use the following methods:
- Log in with an admin account
- Navigate to the 'Control Panel' via the navigation bar at the top of the interface
- Click the 'Restart or Upgrade' button at the top
- If a new version is available, click the 'Upgrade' button. Make sure to carefully read the instructions on the page first.
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.
- Navigate to the folder in which the
docker-compose.yml
file you used to build the containers is located - Remove the existing containers
docker-compose down
- 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) - See Additional Notes for more information, such as Postgres database versions.
- Download the latest 4CAT image
-
docker-compose pull
(Docker will download the version designated in the.env
file set asDOCKER_TAG
)
- Redeploy the containers
docker-compose up -d
- Open a terminal and navigate to the folder 4CAT is running from
- (Optionally) activate the virtual environment
- 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.
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.
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).
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.
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).
- Update the 4cat_backend
docker exec -it 4cat_backend /bin/bash
git pull
- optionally:
git checkout COMMIT_ID
orgit checkout BRANCH_NAME
python3 4cat-daemon.py stop
python3 helper-scripts/migrate.py
- Update the 4cat_frontend
docker exec -it 4cat_backend /bin/bash
git pull
- optionally:
git checkout COMMIT_ID
orgit checkout BRANCH_NAME
python3 helper-scripts/migrate.py
- Restart the containers
cd your/4cat/directory/
docker-compose stop
docker-compose start
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
🐈🐈🐈🐈