Updating¶
When updating from one version to the next, make sure you are aware of the following changes:
Some CATMAID versions require manual changes to an existing setup. Below these and other administration related changes are listed in order. ## 2021.12.21 - The version requires PostgreSQL 12. If you also want to upgrade PostGIS, update PostGIS firstand run ``ALTER EXTENSION postgis UPDATE;`` in every existing database in the cluster that should be upgraded. For docker-compose setups this database update is performed automatically if `DB_UPDATE=true` is set for the `db` container (watch the Docker output). CATMAID's documentation Docker has more information. If a replication setup is in use, the database configuration changes for Postgres 12. CATMAID's replication documentation explains what needs to be done. The next CATMAID release will require Postgres 13, which is also supported by this version. - If R extensions are used, make sure to use R 3.6. On Ubuntu this can be made available by first installing the official R PPA repository: sudo gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-key E084DAB9 sudo gpg -a --export E084DAB9 | sudo apt-key add - echo "deb https://cloud.r-project.org/bin/linux/ubuntu xenial-cran35/" | sudo tee -a /etc/apt/sources.list And second update the package index and update the local R setup: sudo apt-get update sudo apt-get install r-base r-base-dev mesa-common-dev libglu1-mesa-dev \ libssl-dev libssh2-1-dev libcurl4-openssl-dev cmtk This also requires updating all installed R packages. In all likelihood this requires executing "manage.py catmaid_setup_nblast_environment". - The recommended python version is now 3.8, although support for 3.6 is maintained in this version. The next CATMAID release will require at least Python 3.8 and will drop support for Python 3.6. - A virtualenv update is required. - For production environments it is now recommended to also install the Python depedencies listedn in the new requirements-production.txt file: pip install -r requirements-production.txt ## 2020.02.15 - Python 3.5 is not supported anymore. Use Python 3.6, 3.7 or 3.8. - Postgres 11 and PostGIS 2.5 is required, Postgres 12 and PostGIS 3 is recommended. If Postgres needs to be updated, update directly to Postgres 12. If both needs to be updated, update PostGIS first and run ``ALTER EXTENSION postgis UPDATE;`` in every database. For docker-compose setups this database update is performed automatically. If a replication setup is in use, the database configuration changes for Postgres 12. CATMAID's replication documentation explains what needs to be done. - The next version of CATMAID will require Postgres 12 and PostGIS 3. - A virtualenv update is required. Before you start it, please remove some packages that are not needed anymore first: pip uninstall asgi-ipc asgi-rabbitmq - If ASGI was set up before, make sure to install channels_rabbitmq or channels_redis (depending on what yous use). The older asgi_rabbitmq and asgi_redis packages aren't supported anymore. This also requires an update of the CHANNELS_LAYERS in settings.py. The channels_rabbitmq documentation for an example: https://github.com/CJWorkbench/channels_rabbitmq/. This variable isn't defined by default anymore. Therefore you likely have to replace any `CHANNELS_LAYERS[…] = …` with something like `CHANNELS_LAYERS = { … }`. The new format is (use custom credentials on any production system!): ``` CHANNEL_LAYERS = { "default": { "BACKEND": "channels_rabbitmq.core.RabbitmqChannelLayer", "CONFIG": { "host": "amqp://guest:guest@127.0.0.1/asgi", }, }, } ``` Also, if supervisord is in use to manage CATMAID process groups, the main Daphne process needs an adjustment: instead of calling `daphne` with the `mysite.asgi:channel_layer` parameter, use `mysite.asgi:application`. A complete supervisord entry would then look something like this: ``` [program:catmaid-daphne] directory = /home/catmaid/catmaid/django/projects/ command = /home/catmaid/catmaid/django/env/bin/daphne --unix-socket=/var/run/daphne/catmaid.sock --access-log - --proxy-headers mysite.asgi:application user = www-data stdout_logfile = /var/log/daphne/catmaid-server.log redirect_stderr = true ``` As last step, the supervisor entry for the `daphne worker` process has to be removed. New types of workers can be added, but are not needed in most cases. The channels documentation has more information on this. Note, it seems to be also required to upgrade RabbitMQ to the latest version. Using v3.8 worked, while 3.5 didn't. - GDAL v2 or newer is now needed. If your Ubuntu version doesn't support this yet, there is an official PPA: sudo add-apt-repository ppa:ubuntugis/ppa sudo apt-get update - The management command catmaid_populate_summary_tables is now known as catmaid_refresh_node_statistics. - The application of migrations 88-91 and 98-99 might take a while to complete, because they rewrite potentially big database table (treenode_edge, treenode, class_instance, and more). Therefore, make also sure that there is enough space available at the database storage location (25% of database data directory should be plenty). If no replication is used, setting the following Postgres options can speed up the process: `wal_level = minimal`, `archive_mode = off` and `max_wal_senders = 0`. Due to this database update data consistency and correctness was improved, because additional foreign key relationships have been added that were missing before. - Back-end errors result now in actual HTTP error status codes. Third-party clients need possibly some adjustments to handle API errors. In case of an error, status 400 is returned if an input data or parameter problem, 401 for permission problems and 500 otherwise. - On startup, CATMAID will now test if the output directory is accessible as well as if its expected folder layout is present. If expected subfolders are missing, they will now be created. - If R based tools like NBLAST or NRRD export are used, the R environment has to be updated, too. This can be done by calling the following management command: manage.py catmaid_setup_nblast_environment ## 2019.06.20 - A virtualenv update is required. - All \*.pyc files in the folders `django/applications/catmaid/migrations/`, `django/applications/performancetests/migrations/` and `django/applications/pgcompat/migrations/` need to be deleted. - Python 3.7 is now supported. - Heads-up: The next CATMAID version will require Postgres 11, PostGIS 2.5 and Python 3.6 or 3.7. - Should migration 0057 fail due a permission error, the Postgres extension "pg_trgm" has to be installed manually into the CATMAID database using a Postgres superuser: `sudo -u postgres psql -d <catmaid-db> -c 'CREATE EXTENSION pg_trgm;'` - CATMAID's version information changes back to a plain `git describe` format. This results overall in a simpler setup and makes live easier for some third-party front-ends, because the commit counter is included again. The version display is now the same `git describe` format for both regular setups and Docker containers. - Tile loading is clamped to (0,0) again, i.e. there are no negative tile coordinates anymore by default. If you need them, set the respective stack's `metadata` field to `{"clamp": false}`. - To write to CATMAID through its API using an API token, users need to have now dedicated "API write" permission, called "Can annotate project using API token" in the admin UI. To restore the previous behavior (regular annotate permission allows API write access) the settings.py variable `REQUIRE_EXTRA_TOKEN_PERMISSIONS` can be set to `False`. This is done as a safety measure to prevent accidental changes through automation. - If R based NBLAST is used, make sure to execute to update all dependencies: `manage.py catmaid_setup_nblast_environment`. - The main documentation on catmaid.org has now a place for widget specific documentation as well. Only a few widgets have been updated yet, but more will follow. ## 2018.11.09 - Python 3 is now required for the back-end. We recommend the use of Python 3.6. ## 2018.07.19 - This is the last CATMAID version with support for Python 2.7. Starting from next version, only Python 3 will be supported. ## 2018.04.15 - Postgres 10+ is now required. ## 2018.02.16 - Three new OS package dependencies have been added (due to a Django framework upgrade), make sure they are installed: `sudo apt-get install binutils libproj-dev gdal-bin` - Python 3.6 is now supported. Make sure to update your settings.py by replacing the line `COOKIE_SUFFIX = hashlib.md5(CATMAID_URL).hexdigest()` with the following line: `COOKIE_SUFFIX = hashlib.md5(CATMAID_URL.encode('utf-8')).hexdigest()` - CATMAID extensions no longer require users to manually update their `INSTALLED_APPS` in `settings.py`. Remove if they are already in use. - The `NODE_PROVIDER` settings variable (`settings.py`) is replaced with the `NODE_PROVIDERS` variable. The new variable takes a list of node provider names, which are iterated as long as no result nodes are found. Replace the former single string value with a list with this name as single element, e.g. if the current setting reads `NODE_PROVIDER = 'postgis2d'`, replace it with `NODE_PROVIDERS = ['postgis2d']`. ## 2017.12.07 - PostgreSQL 9.6 and Postgis 2.4 are now required. - A `virtualenv` upgrade is required. To correctly install one updated dependency, the `django-rest-swagger` Python package has to be removed first from from the `virtualenv`, before the `virtualenv` is updated: ``` pip uninstall django-rest-swagger pip install -r requirements.txt ``` - Requires running of: `manage.py catmaid_update_project_configuration` - Tracing data is now by default transmitted in a binary form, please make therefore sure your web-server applies GZIP not only to the `application/json` content type, but also to `application/octet-stream`. For Nginx this would be the gzip_types setting. ## 2017.07.28 - The following lines have to be removed from `settings.py`, ``` import djcelery djcelery.setup_loader() INSTALLED_APPs += ("kombu.transport.django") BROKER_URL = 'django://' ``` ## 2017.05.17 - A `virtualenv` upgrade is required. To correctly install one updated dependency, the `django-rest-swagger` Python package has to be removed first from from the `virtualenv`, before the `virtualenv` is updated: ``` pip uninstall django-rest-swagger pip install -r requirements.txt ``` ## 2017.04.20 - The location of the `manage.py` script changed: it moved a level up into `django/projects`. All other configuration files remain where they are. Make sure to update your `settings.py` file by replacing the line `from settings_base import *` with `from mysite.settings_base import *`.
