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.

Verifying image signatures (recommended pre-upgrade step)¶

Release images are signed with cosign using keyless Sigstore/OIDC signing — there is no public key to distribute. The signature proves the image was built by this repository's release.yml workflow, from a v* tag, and has not been altered in the registry since.

Verify before you pull into production. This is a manual operator step: nothing in the Compose stack verifies signatures automatically, so an unverified upgrade will proceed silently.

Install cosign (v2 or newer — v1 needs COSIGN_EXPERIMENTAL=1 and is not supported here):

# See https://docs.sigstore.dev/cosign/system_config/installation/ for other platforms
curl -sSLo cosign https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
chmod +x cosign && sudo mv cosign /usr/local/bin/

Verify both images for the tag you are about to deploy:

export CLIMATE_LAMA_TAG=v0.5.0   # the tag you intend to run

for IMAGE in climate-lama climate-lama-worker; do
  cosign verify \
    --certificate-identity-regexp '^https://github\.com/CortoMaltese3/climate-lama/\.github/workflows/release\.yml@refs/tags/v' \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    "ghcr.io/cortomaltese3/${IMAGE}:${CLIMATE_LAMA_TAG}"
done

A successful run prints the certificate subject and the Rekor transparency-log entry, and exits 0. Any non-zero exit means do not deploy that image — treat it as a supply-chain incident, not a tooling glitch, and report it on the issue tracker before proceeding.

The identity regexp is deliberately narrow: it pins the signer to release.yml running on a v* tag in this repository. A looser pattern (e.g. .../climate-lama/.*) would also accept a signature minted by any other workflow in the repo, which is a weaker claim.

Notes:

Signatures are bound to the image digest, not the tag. Verifying :v0.5.0 resolves the tag to its digest and checks the signature on that digest, so a re-pointed tag cannot reuse an older signature.
Only releases published after 2026-08-01 are signed. v0.4.0 and earlier were built before signing landed and will fail verification with "no matching signatures" — that is expected for those tags, not a compromise.
Verification reads Sigstore's public Rekor log, so the machine running it needs outbound network access. Fully air-gapped verification is not supported today.

Upgrade procedure¶

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

# 2. Verify the images are signed by this repo's release workflow (see above)

# 3. Pull the new images
docker compose pull

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

# 5. 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.