Upgrading Climate-Lama¶

This page covers how to upgrade a self-hosted Climate-Lama instance to a new release.

Finding the latest release¶

Published image tags are listed on GHCR:

Stable releases follow v{major}.{minor}.{patch} semver. Pre-release candidates are tagged v{major}.{minor}.{patch}-rc{N} (e.g., v0.1.0-rc1) and never update latest.

Upgrade procedure¶

# 1. Set the target version
export CLIMATE_LAMA_TAG=v0.2.0   # replace with the desired tag

# 2. Pull the new images
docker compose pull

# 3. Run database migrations before starting the new containers
docker compose run --rm migrations

# 4. Restart services with the new images
docker compose up -d

Verify the API is healthy:

curl http://localhost:8000/v1/health

Rollback¶

Re-pin CLIMATE_LAMA_TAG to the prior tag and restart:

export CLIMATE_LAMA_TAG=v0.1.0
docker compose pull
docker compose up -d

Only run alembic downgrade if the release notes for the version you are rolling back from explicitly document a reversible migration step. Most migrations are forward-only; check the changelog before attempting a schema downgrade.

Pre-release tags¶

Tags matching v*-rc* are pre-release candidates. They are built and pushed to GHCR by the same release pipeline but never update latest. Use them to validate a new release in a staging environment before rolling to production:

CLIMATE_LAMA_TAG=v0.2.0-rc1 docker compose pull && docker compose up -d

Pinning in production¶

docker-compose.yml defaults to latest via ${CLIMATE_LAMA_TAG:-latest}. For production deployments, always pin to an explicit semver tag in your .env file:

CLIMATE_LAMA_TAG=v0.2.0

This prevents unintentional upgrades on docker compose pull.