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.
- Stop WAMF cleanly:
docker compose stop wamf. - Back up
config/,data/andmedia/together. - Retain the previous image locally for rollback.
- Preserve mounts, ports, credentials and
WAMF_SECRET_KEY, if set. - Set the service image to
ghcr.io/wamf-project/wamf:0.4.3. - 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.
- Stop WAMF cleanly before taking a backup, for example with
docker compose stop wamf. - Back up the complete
config/,data/andmedia/directories together. - Keep the previous image locally available for rollback; do not prune it before verifying the upgrade.
- Preserve the existing mounts, port mappings and
WAMF_SECRET_KEYenvironment value, if set. Retain any additional/dataor/mediacompatibility mounts already used by an older installation. - 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:
You can also check the running container with:
For WAMF v0.4.0, the image is:
Back Up WAMF¶
Before updating, preserve the WAMF persistent directories:
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:
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:
Recreate the container:
Docker Compose will replace the container while retaining the bind-mounted WAMF configuration, database and media directories.
Check the container status:
Then review the startup logs:
Portainer¶
For a Portainer deployment:
- Open the WAMF stack.
- Change the WAMF image tag to the required version.
- Update or redeploy the stack.
- Allow Portainer to pull the updated image.
- Check the WAMF container logs after deployment.
The existing bind-mounted config, data and media directories should remain unchanged.
Verify the Update¶
After updating:
- Open the WAMF web interface.
- Confirm that WAMF starts normally.
- Check the system health information.
- Confirm that WAMF connects to MQTT.
- Confirm that WAMF can communicate with Frigate.
- Verify that existing observations and archived media are still available.
- Test or wait for a new bird detection and confirm that it is processed successfully.
- Confirm that the existing administrator login and API token still work.
- 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:
Then pull and recreate the container:
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:
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.