Skip to content

Updating WAMF

WAMF Docker releases are published as versioned images on the GitHub Container Registry.

The current stable release is v0.4.3, for AMD64 (x86-64) deployments. See the v0.4.3 release notes for changes and retained security limitations.

Upgrading v0.4.2 to v0.4.3

No configuration, database or media migration is introduced. Existing valid credentials and session secrets are preserved.

  1. Stop WAMF cleanly: docker compose stop wamf.
  2. Back up config/, data/ and media/ together.
  3. Retain the previous image locally for rollback.
  4. Preserve mounts, ports, credentials and WAMF_SECRET_KEY, if set.
  5. Set the service image to ghcr.io/wamf-project/wamf:0.4.3.
  6. Pull and recreate it using the Docker Compose or Portainer steps below.

After upgrading, verify login, API access, archived media, MQTT detection and restart persistence. Also check internal links, date selection, browser back/forward and Home Assistant embedded navigation. For rollback, stop the upgraded container and select the previous 0.4.2 image using the same mounts and session-secret setting. Never run both versions as database writers. Restore the corresponding pre-upgrade backup if needed.

Historical upgrade: v0.4.0 or v0.4.1 to v0.4.2

The following section preserves the older upgrade path. For the current stable release, follow the v0.4.3 procedure above.

Existing provisioned installations with valid credentials require no configuration, database or media migration and no credential reset.

  1. Stop WAMF cleanly before taking a backup, for example with docker compose stop wamf.
  2. Back up the complete config/, data/ and media/ directories together.
  3. Keep the previous image locally available for rollback; do not prune it before verifying the upgrade.
  4. Preserve the existing mounts, port mappings and WAMF_SECRET_KEY environment value, if set. Retain any additional /data or /media compatibility mounts already used by an older installation.
  5. Set the image to ghcr.io/wamf-project/wamf:0.4.2, then pull and recreate it using the instructions below.

Mount the entire writable configuration directory. Single-file and read-only configuration mounts cannot support atomic configuration replacement.

Valid administrator passwords, API credentials and session secrets are preserved. Malformed or unsupported authentication configuration stops startup rather than resetting credentials. Only a genuinely unprovisioned installation receives a first-run setup link; see Authentication.

Before updating, back up your WAMF configuration, database and media.

See Backup & Restore for the recommended backup procedure.

Check the Current Version

If WAMF is running with Docker Compose, check the configured image:

docker compose config | grep image

You can also check the running container with:

docker ps --filter name=wamf

For WAMF v0.4.0, the image is:

ghcr.io/wamf-project/wamf:0.4.0

Back Up WAMF

Before updating, preserve the WAMF persistent directories:

config/
data/
media/

These contain the WAMF configuration, database and archived media.

For the most consistent database backup, stop WAMF before copying these directories.

Update the Image Version

Edit your Docker Compose or Portainer stack and change the WAMF image tag to the version you want to install.

For the current v0.4.3 upgrade, set:

image: ghcr.io/wamf-project/wamf:0.4.3

Using an explicit version tag is recommended because it makes upgrades deliberate and makes it clear which WAMF release is running.

Docker Compose

After changing the image version, pull the new image:

docker compose pull wamf

Recreate the container:

docker compose up -d

Docker Compose will replace the container while retaining the bind-mounted WAMF configuration, database and media directories.

Check the container status:

docker compose ps

Then review the startup logs:

docker compose logs -f wamf

Portainer

For a Portainer deployment:

  1. Open the WAMF stack.
  2. Change the WAMF image tag to the required version.
  3. Update or redeploy the stack.
  4. Allow Portainer to pull the updated image.
  5. Check the WAMF container logs after deployment.

The existing bind-mounted config, data and media directories should remain unchanged.

Verify the Update

After updating:

  1. Open the WAMF web interface.
  2. Confirm that WAMF starts normally.
  3. Check the system health information.
  4. Confirm that WAMF connects to MQTT.
  5. Confirm that WAMF can communicate with Frigate.
  6. Verify that existing observations and archived media are still available.
  7. Test or wait for a new bird detection and confirm that it is processed successfully.
  8. Confirm that the existing administrator login and API token still work.
  9. Restart or recreate the container and verify that credentials, observations and archived media persist.

Rollback

If an update causes a problem, stop WAMF and restore the backup made before the update if required.

Use the same mounts, port mappings and session-secret environment value. Never run the old and new containers as simultaneous writers to the database.

Change the image tag back to the previous version.

For example:

image: ghcr.io/wamf-project/wamf:0.4.0

Then pull and recreate the container:

docker compose pull wamf
docker compose up -d

If the newer WAMF release changed persistent data or configuration in a way that is not compatible with the previous release, restore the corresponding pre-update backup before starting the older version.

Always check the release notes for version-specific upgrade or rollback instructions.

Image Tags

WAMF releases use versioned container tags.

For the current stable release:

ghcr.io/wamf-project/wamf:0.4.3

The v0.4.3 publishing workflow does not update latest. Select the explicit ghcr.io/wamf-project/wamf:0.4.3 tag for the current stable release; do not assume that an existing latest image contains this release.