Migration Guide

Version 2.13

Version 2.13 deprecates the portainer component

If you are currently using the portainer component in your stack change the entry in the BIRDHOUSE_EXTRA_CONF_DIRS variable from ./components/portainer to deprecated-components/portainer.

Consider using a different solution than portainer going forward since this component may be removed completely in future versions.

Version 2.9

Version 2.9 updates JupyterHub to version 5.

To upgrade to version 2.9 from an earlier version:

  • If your local environment file sets the c.DockerSpawner.image_whitelist config option in the JUPYTERHUB_ENABLE_MULTI_NOTEBOOKS environment variable. Change c.DockerSpawner.image_whitelist to c.DockerSpawner.allowed_images.

    If you have changed any of the default jupyterhub settings you may need to consult the JupyterHub upgrade guide to see if any of those settings have been changed.

Version 2.7.3

Version 2.7.3 introduced docker compose syntax that is incompatible with docker compose versions older than 2.20.2.

  • If your docker compose version is older than 2.20.2 you should update to the latest version of docker compose as soon as possible.

  • You may also want to update any docker compose version 1 syntax at this time to avoid deprecation warnings right now (and deployment failures in the future if the version 1 syntax eventually is no longer supported).

    Version 1 syntax may include:

    • top level version keys

    • declaring volumes and networks as external with the external: <name> syntax (where name is the name of the volume or network) instead of external: true.

Version 2.4

Version 2.4 renames files and variables that included the string PAVICS.

For historical reasons the name PAVICS was used in variable names, constants and filenames in this repo to refer to the software stack in general. This was because, for a long time, the PAVICS deployment of this stack was the only one that was being used in production. However, now that multiple deployments of this software exist in production (that are not named PAVICS), we remove unnecessary references to PAVICS in order to reduce confusion for maintainers and developers who may not be aware of the historical reasons for the PAVICS name.

To upgrade to version 2.4 from an earlier version, please follow these steps:

  1. Update env.local file to replace all variables that contain PAVICS with BIRDHOUSE. Variable names have also been updated to ensure that they start with the prefix BIRDHOUSE_.

  2. Update any external scripts that access the old variable names directly to use the updated variable names.

  3. Update any external scripts that access any of the following files to use the new file name:

    old file name

    new file name

    pavics-compose.sh

    birdhouse-compose.sh

    PAVICS-deploy.logrotate

    birdhouse-deploy.logrotate

    configure-pavics.sh

    configure-birdhouse.sh

    trigger-pavicscrawler

    trigger-birdhousecrawler

  4. Update any external scripts that called pavics-compose.sh or read-configs.include.sh to use the CLI entrypoint in bin/birdhouse instead.

  5. The following default values have changed. If your deployment was using the old default value, update your env.local file to explicitly set the old default values.

    old variable name

    new variable name

    old default value

    new default value

    POSTGRES_PAVICS_USERNAME

    BIRDHOUSE_POSTGRES_USERNAME

    postgres-pavics

    postgres-birdhouse

    THREDDS_DATASET_LOCATION_ON_CONTAINER

    (no change)

    /pavics-ncml

    /birdhouse-ncml

    THREDDS_SERVICE_DATA_LOCATION_ON_CONTAINER

    (no change)

    /pavics-data

    /birdhouse-data

    (hardcoded)

    BIRDHOUSE_POSTGRES_DB

    pavics

    birdhouse

    PAVICS_LOG_DIR

    BIRDHOUSE_LOG_DIR

    /var/log/PAVICS

    /var/log/birdhouse

    (hardcoded)

    GRAFANA_DEFAULT_PROVIDER_FOLDER

    Local-PAVICS

    Local-Birdhouse

    (hardcoded)

    GRAFANA_DEFAULT_PROVIDER_FOLDER_UUID

    local-pavics

    local-birdhouse

    (hardcoded)

    GRAFANA_PROMETHEUS_DATASOURCE_UUID

    local_pavics_prometheus

    local_birdhouse_prometheus

    Note that the PAVICS_LOG_DIR variable was actually hardcoded as /var/log/PAVICS in some scripts. If PAVICS_LOG_DIR was set to anything other than /var/log/PAVICS you’ll end up with inconsistent log outputs as previously some logs would have been sent to PAVICS_LOG_DIR and others to /var/log/PAVICS. We recommend merging these two log files. Going forward, all logs will be sent to BIRDHOUSE_LOG_DIR.

  6. Update any jupyter notebooks that make use of the PAVICS_HOST_URL environment variable to use the new BIRDHOUSE_HOST_URL instead.

  7. Set the BIRDHOUSE_POSTGRES_DB variable to pavics in the env.local file. This value was previously hardcoded to the string pavics so to maintain backwards compatibility with any existing databases this should be kept the same. If you do want to update to the new database name, you will need to rename the existing database. For example, the following will update the existing database named pavics to birdhouse (assuming the old default values for the postgres username):

    docker exec -it postgres psql -U postgres-pavics -d postgres -c 'ALTER DATABASE pavics RENAME TO birdhouse'

    You can then update the env.local file to the new variable name and restart the stack

  8. Set the BIRDHOUSE_POSTGRES_USER variable to postgres-pavics in the env.local file if you would like to preserve the old default value. If you would like to change the value of BIRDHOUSE_POSTGRES_USER then also update the name for any running postgres instances. For example, the following will update the user named postgres-pavics to postgres-birdhouse:

    docker exec -it postgres psql -U postgres-pavics -d postgres -c 'CREATE USER "tmpsuperuser" WITH SUPERUSER'
docker exec -it postgres psql -U tmpsuperuser -d postgres -c 'ALTER ROLE "postgres-pavics" RENAME TO "postgres-birdhouse"'
docker exec -it postgres psql -U tmpsuperuser -d postgres -c 'ALTER ROLE "postgres-birdhouse" WITH PASSWORD '\''postgres-qwerty'\'
docker exec -it postgres psql -U postgres-birdhouse -d postgres -c 'DROP ROLE "tmpsuperuser"'

    Note that the postgres-qwerty value is meant just for illustration, you should replace this with the value of the BIRDHOUSE_POSTGRES_PASSWORD variable. Note that you’ll need to do the same for the stac-db service as well (assuming that you weren’t previously overriding the STAC_POSTGRES_USER with a custom value).