Migration Guide =============== .. shared references by multiple components definitions .. NOTE: .. Because this file is in 'docs/source' rather than under 'birdhouse' like other 'README.rst', the link hack won't work here. .. There is no way to provide a common link in this case since their directory structure are fundamentally different, .. and GitHub will not process the 'birdhouse' symlink directly. As a workaround, the links in this file will use the .. native path that works on GitHub, and the Sphinx pre-processor will rewrite them to the correct path during build. .. |birdhouse-default.env| replace:: ``birdhouse/default.env`` .. _birdhouse-default.env: ../../birdhouse/default.env .. |birdhouse-env.local.example| replace:: ``birdhouse/env.local.example`` .. _birdhouse-env.local.example: ../../birdhouse/env.local.example .. contents:: 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. .. |deprecated-components-portainer| replace:: ``deprecated-components/portainer`` .. _deprecated-components-portainer: ../../birdhouse/deprecated-components/portainer/ 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: `` 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_``. * see |birdhouse-env.local.example|_ to see new variable names * see the ``BIRDHOUSE_BACKWARDS_COMPATIBLE_VARIABLES`` variable (defined in |birdhouse-default.env|_) for a full list of changed environment variable names. 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: .. list-table:: :header-rows: 1 * - 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. .. list-table:: :header-rows: 1 * - 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): .. code-block:: shell 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``: .. code-block:: shell 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).