[bug] docker-compose uses 'latest' tags; should use version numbers

[pandafy]

Describe the bug
Using latest tags in docker-compose can cause unwanted upgrades if using docker compose pull instead of make pull (which pulls the correct image and tag them as latest). This may accidentally pull incompatible versions and break a working deployment unexpectedly. This is especially risky for users running older or stable releases (for example, 24.11), because pulling will download newer images (e.g., 25.10.1) without warning.

Steps To Reproduce

1. Deploy using docker-compose for a specific release (e.g., 24.11)
2. Run docker compose pull
3. Docker downloads images tagged as latest (typically the newest release)
4. Deployment may break due to incompatibility or unexpected updates

Expected behavior
Images should always match the intended release version in the compose file, avoiding accidental upgrades or mismatches regardless of command usage.

Screenshots
N/A

System Informatioon:

• OS: Any
• Docker version: Any
• Browser and Browser Version (if applicable): N/A
• Additional context: The workflow currently relies on make pull to determine and overwrite the tags as latest, but this is not a reliable safeguard against accidental upgrades.

[atif09]

ill work on this

Proposed Solution

1) add DOCKER_TAG environment variable

• add DOCKER_TAG=latest to the .env file
• this becomes the single source of truth for image versioning across all workflows
• defaults to latest for backward compatibility

2) update docker-compose.yml

• replace all hardcoded :latest image tags with ${DOCKER_TAG:-latest}

3) update makefiles pull target

• modify from openwisp/$${image}:latest to openwisp/$${image}:${DOCKER_TAG:-latest}
• ensures both make pull and docker compose pull respect the same version

[pandafy]

Cross-posted from #555 (review)

The proposal is to introduce an OPENWISP_VERSION variable in the .env file, defaulting to edge, and update docker-compose.yml to reference images using openwisp/:${OPENWISP_VERSION}.

This approach allows the same configuration to support both local development builds and versioned, registry-based images, creating a clear distinction between development flexibility and production stability.

Effects on development flow

The development workflow remains essentially unchanged. Developers can continue using Makefile or docker compose commands directly. The default configuration will always use edge images. This makes working on new changes easy.

Effects on the release flow

edge images

edge images are published on every push to the master branch. This behavior is driven by the CI workflow and is unaffected by the proposed changes, so the edge release flow will remain exactly as it is today.

Versioned images (e.g. 25.10.2)

Currently, versioned images use the OPENWISP_VERSION value defined in the Makefile. With this proposal, OPENWISP_VERSION moves to .env and defaults to edge, where it becomes a runtime configuration rather than a release signal. As a result, it can no longer serve as the source of truth for release versioning.

To preserve a declarative and easy-to-maintain release process, we need a separate variable in the Makefile that explicitly defines the release version. This keeps the release version documented, version-controlled, and independent of runtime configuration.

While it would be possible to derive the version automatically from the latest Git tag, a declarative Makefile variable is preferred for clarity, predictability, and maintainability.

Effects on deployment

The auto-install script writes the user-selected version into the .env file during setup (defaulting to latest). As a result, deployments will use the latest stable images (e.g. 25.10). Alternatively, the user can enter the version number. This guarantees safer upgrades and predictable, reproducible installations without adding complexity to the development workflow.

If a user clones the docker-openwisp repository and spins up OpenWISP without using the auto-install script, then they will end up with the edge images (development version of OpenWISP).