[change] Make image registry and namespace configurable

.env

@@ -4,8 +4,9 @@
 # Essential
 DASHBOARD_DOMAIN=dashboard.openwisp.org
 API_DOMAIN=api.openwisp.org
-# Image tag pinning
-IMAGE_OWNER=openwisp
+# Image location and tag pinning
+# IMAGE_REGISTRY=docker.io
+# IMAGE_NAMESPACE=openwisp
 # OPENWISP_VERSION: Image tag version (e.g., "25.10.0", "latest", or "edge")
 OPENWISP_VERSION=edge
 # SSH Credentials Configurations

.github/workflows/ci.yml

@@ -138,7 +138,7 @@ jobs:
       - name: Publish to Docker Hub
         if: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
         run: |
-          make publish USER=docker.io/openwisp TAG=edge SKIP_BUILD=true SKIP_TESTS=true
+          make publish TAG=edge SKIP_BUILD=true SKIP_TESTS=true
         env:
           SELENIUM_HEADLESS: 1
 
@@ -154,4 +154,4 @@ jobs:
       - name: Publish to GitLab Container Registry
         if: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
         run: |
-          make publish USER=registry.gitlab.com/openwisp/docker-openwisp TAG=edge SKIP_BUILD=true SKIP_TESTS=true
+          make publish IMAGE_REGISTRY=registry.gitlab.com TAG=edge SKIP_BUILD=true SKIP_TESTS=true

.github/workflows/release.yml

@@ -34,7 +34,7 @@ jobs:
 
       - name: Release to Docker Hub
         run: |
-          make release USER=docker.io/openwisp
+          make release
 
       - name: Login to GitLab Container Registry
         uses: docker/login-action@v4.6.0
@@ -45,4 +45,4 @@ jobs:
 
       - name: Release to GitLab Container Registry
         run: |
-          make release USER=registry.gitlab.com/openwisp/docker-openwisp SKIP_BUILD=true
+          make release IMAGE_REGISTRY=registry.gitlab.com SKIP_BUILD=true

Makefile

@@ -1,7 +1,7 @@
 # Find documentation in README.md under
 # the heading "Makefile Options".
 
-# The .env file can override ?= variables in the Makefile (e.g. OPENWISP_VERSION, IMAGE_OWNER)
+# The .env file can override ?= variables in the Makefile (e.g. OPENWISP_VERSION, IMAGE_REGISTRY)
 include .env
 
 # RELEASE_VERSION: version string used when tagging a new release.
@@ -11,12 +11,25 @@ SHELL := /bin/bash
 
 default: compose-build
 
-USER = docker.io/openwisp
 TAG = edge
 # OPENWISP_VERSION: image tag used for pulling/pushing images (e.g. "edge", "latest", "25.10.0")
 # Can be overridden via .env or command line. Not the same as RELEASE_VERSION
 OPENWISP_VERSION ?= edge
-IMAGE_OWNER ?= openwisp
+IMAGE_REGISTRY ?= docker.io
+# Use Docker Hub when IMAGE_REGISTRY is unset or empty.
+ifeq ($(strip $(IMAGE_REGISTRY)),)
+override IMAGE_REGISTRY := docker.io
+endif
+# TODO: Remove IMAGE_OWNER compatibility in the next major release.
+ifneq ($(strip $(IMAGE_OWNER)),)
+$(warning IMAGE_OWNER is deprecated. Use IMAGE_REGISTRY and IMAGE_NAMESPACE instead.)
+endif
+# Fall back to either the old IMAGE_OWNER (if set) or "openwisp" when IMAGE_NAMESPACE is unset or empty.
+# TODO: Remove IMAGE_OWNER compatibility in the next major release.
+ifeq ($(strip $(IMAGE_NAMESPACE)),)
+override IMAGE_NAMESPACE := $(if $(strip $(IMAGE_OWNER)),$(IMAGE_OWNER),openwisp)
+endif
+IMAGE_PREFIX = $(IMAGE_REGISTRY)/$(IMAGE_NAMESPACE)
 SKIP_PULL ?= false
 SKIP_BUILD ?= false
 SKIP_TESTS ?= false
@@ -28,8 +41,7 @@ pull:
 	for image in 'openwisp-base' 'openwisp-nfs' 'openwisp-api' 'openwisp-dashboard' \
 				 'openwisp-freeradius' 'openwisp-nginx' 'openwisp-openvpn' 'openwisp-postfix' \
 				 'openwisp-websocket' ; do \
-		docker pull --quiet $(USER)/$${image}:$(OPENWISP_VERSION) || exit 1; \
-		docker tag $(USER)/$${image}:$(OPENWISP_VERSION) $(IMAGE_OWNER)/$${image}:$(OPENWISP_VERSION) || exit 1; \
+		docker pull --quiet $(IMAGE_PREFIX)/$${image}:$(OPENWISP_VERSION) || exit 1; \
 	done
 
 # Build
@@ -41,20 +53,20 @@ base-build:
 	for build_arg in $$BUILD_ARGS_FILE; do \
 	    BUILD_ARGS+=" --build-arg $$build_arg"; \
 	done; \
-	docker build --tag openwisp/openwisp-base:intermedia-system \
+	docker build --tag $(IMAGE_PREFIX)/openwisp-base:intermedia-system \
 	             --file ./images/openwisp_base/Dockerfile \
 	             --target system ./images/; \
-	docker build --tag openwisp/openwisp-base:intermedia-python \
+	docker build --tag $(IMAGE_PREFIX)/openwisp-base:intermedia-python \
 	             --file ./images/openwisp_base/Dockerfile \
 	             --target openwisp_python ./images/ \
 	             $$BUILD_ARGS; \
-	docker build --tag $(IMAGE_OWNER)/openwisp-base:$(OPENWISP_VERSION) \
+	docker build --tag $(IMAGE_PREFIX)/openwisp-base:$(OPENWISP_VERSION) \
 	             --file ./images/openwisp_base/Dockerfile \
 	             $$BUILD_ARGS \
 	             ./images/
 
 nfs-build:
-	docker build --tag $(IMAGE_OWNER)/openwisp-nfs:$(OPENWISP_VERSION) \
+	docker build --tag $(IMAGE_PREFIX)/openwisp-nfs:$(OPENWISP_VERSION) \
 	             --file ./images/openwisp_nfs/Dockerfile ./images/
 
 compose-build: base-build
@@ -72,7 +84,7 @@ develop-runtests:
 develop-pythontests:
 	# OPENWISP_TEST_OPENVPN_IMAGE is used in tests to run OpenVPN tests with the
 	# latest locally built image rather than the image published in the registries.
-	OPENWISP_TEST_OPENVPN_IMAGE=$(IMAGE_OWNER)/openwisp-openvpn:$(OPENWISP_VERSION) \
+	OPENWISP_TEST_OPENVPN_IMAGE=$(IMAGE_PREFIX)/openwisp-openvpn:$(OPENWISP_VERSION) \
 		python3 tests/runtests.py
 
 # Development
@@ -86,10 +98,10 @@ clean:
 	docker compose stop &> /dev/null
 	docker compose down --remove-orphans --volumes --rmi all &> /dev/null
 	docker compose rm -svf &> /dev/null
-	docker rmi --force openwisp/openwisp-base:intermedia-system \
-				openwisp/openwisp-base:intermedia-python \
-				$(IMAGE_OWNER)/openwisp-base:$(OPENWISP_VERSION) \
-				$(IMAGE_OWNER)/openwisp-nfs:$(OPENWISP_VERSION) \
+	docker rmi --force $(IMAGE_PREFIX)/openwisp-base:intermedia-system \
+				$(IMAGE_PREFIX)/openwisp-base:intermedia-python \
+				$(IMAGE_PREFIX)/openwisp-base:$(OPENWISP_VERSION) \
+				$(IMAGE_PREFIX)/openwisp-nfs:$(OPENWISP_VERSION) \
 				`docker images -f "dangling=true" -q` \
 				`docker images | grep openwisp/docker-openwisp | tr -s ' ' | cut -d ' ' -f 3` &> /dev/null
 
@@ -119,16 +131,34 @@ publish:
 	if [[ "$(SKIP_TESTS)" == "false" ]]; then \
 		make runtests; \
 	fi
+	# CI builds Docker Hub images before overriding IMAGE_REGISTRY for publishing.
+	# With SKIP_BUILD=true, use those existing namespace-only source tags.
+	if [[ "$(SKIP_BUILD)" == "true" ]]; then \
+		source_prefix=$(IMAGE_NAMESPACE); \
+	else \
+		source_prefix=$(IMAGE_PREFIX); \
+	fi; \
 	for image in 'openwisp-base' 'openwisp-nfs' 'openwisp-api' 'openwisp-dashboard' \
 				 'openwisp-freeradius' 'openwisp-nginx' 'openwisp-openvpn' 'openwisp-postfix' \
 				 'openwisp-websocket' ; do \
-		docker tag $(IMAGE_OWNER)/$${image}:$(OPENWISP_VERSION) $(USER)/$${image}:$(TAG) || exit 1; \
-		docker push $(USER)/$${image}:$(TAG) || exit 1; \
+		source=$$source_prefix/$${image}:$(OPENWISP_VERSION); \
+		destination=$(IMAGE_PREFIX)/$${image}:$(TAG); \
+		if [ "$$source" != "$$destination" ]; then \
+			docker tag "$$source" "$$destination" || exit 1; \
+		fi; \
+		docker push "$$destination" || exit 1; \
 	done
 
 release:
 	make publish TAG=latest OPENWISP_VERSION=$(RELEASE_VERSION) SKIP_TESTS=true
-	make publish TAG=$(RELEASE_VERSION) OPENWISP_VERSION=$(RELEASE_VERSION) SKIP_BUILD=true SKIP_TESTS=true
+	# A custom-registry release rebuilds before publishing the versioned tag.
+	# SKIP_BUILD=true would otherwise use the Docker Hub source tags reserved for CI.
+	if [[ "$(SKIP_BUILD)" == "true" || "$(IMAGE_REGISTRY)" == "docker.io" ]]; then \
+		skip_build=true; \
+	else \
+		skip_build=false; \
+	fi; \
+	make publish TAG=$(RELEASE_VERSION) OPENWISP_VERSION=$(RELEASE_VERSION) SKIP_BUILD=$$skip_build SKIP_TESTS=true
 
 bump:
 	@if [ -z "$(VERSION)" ]; then \

docker-compose.yml

@@ -12,13 +12,14 @@ x-celery-depends-on: &celery-depends-on
 
 services:
   dashboard:
-    image: ${IMAGE_OWNER:-openwisp}/openwisp-dashboard:${OPENWISP_VERSION:-edge}
+    image: ${IMAGE_REGISTRY:-docker.io}/${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}/openwisp-dashboard:${OPENWISP_VERSION:-edge}
     restart: always
     build:
       context: images
       dockerfile: openwisp_dashboard/Dockerfile
       args:
-        IMAGE_OWNER: ${IMAGE_OWNER:-openwisp}
+        IMAGE_REGISTRY: ${IMAGE_REGISTRY:-docker.io}
+        IMAGE_NAMESPACE: ${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}
         DASHBOARD_APP_PORT: 8000
         OPENWISP_VERSION: ${OPENWISP_VERSION:-edge}
     env_file:
@@ -38,13 +39,14 @@ services:
       - influxdb
 
   api:
-    image: ${IMAGE_OWNER:-openwisp}/openwisp-api:${OPENWISP_VERSION:-edge}
+    image: ${IMAGE_REGISTRY:-docker.io}/${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}/openwisp-api:${OPENWISP_VERSION:-edge}
     restart: always
     build:
       context: images
       dockerfile: openwisp_api/Dockerfile
       args:
-        IMAGE_OWNER: ${IMAGE_OWNER:-openwisp}
+        IMAGE_REGISTRY: ${IMAGE_REGISTRY:-docker.io}
+        IMAGE_NAMESPACE: ${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}
         API_APP_PORT: 8001
         OPENWISP_VERSION: ${OPENWISP_VERSION:-edge}
     env_file:
@@ -60,13 +62,14 @@ services:
       - dashboard
 
   websocket:
-    image: ${IMAGE_OWNER:-openwisp}/openwisp-websocket:${OPENWISP_VERSION:-edge}
+    image: ${IMAGE_REGISTRY:-docker.io}/${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}/openwisp-websocket:${OPENWISP_VERSION:-edge}
     restart: always
     build:
       context: images
       dockerfile: openwisp_websocket/Dockerfile
       args:
-        IMAGE_OWNER: ${IMAGE_OWNER:-openwisp}
+        IMAGE_REGISTRY: ${IMAGE_REGISTRY:-docker.io}
+        IMAGE_NAMESPACE: ${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}
         WEBSOCKET_APP_PORT: 8002
         OPENWISP_VERSION: ${OPENWISP_VERSION:-edge}
     env_file:
@@ -77,7 +80,7 @@ services:
       - dashboard
 
   celery:
-    image: ${IMAGE_OWNER:-openwisp}/openwisp-dashboard:${OPENWISP_VERSION:-edge}
+    image: ${IMAGE_REGISTRY:-docker.io}/${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}/openwisp-dashboard:${OPENWISP_VERSION:-edge}
     # Keep this longer than Supervisor's stopwaitsecs to let it reap workers and exit.
     stop_grace_period: 120s
     restart: always
@@ -94,7 +97,7 @@ services:
     network_mode: "${CELERY_SERVICE_NETWORK_MODE-service:openvpn}"
 
   celery_monitoring:
-    image: ${IMAGE_OWNER:-openwisp}/openwisp-dashboard:${OPENWISP_VERSION:-edge}
+    image: ${IMAGE_REGISTRY:-docker.io}/${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}/openwisp-dashboard:${OPENWISP_VERSION:-edge}
     # Keep this longer than Supervisor's stopwaitsecs to let it reap workers and exit.
     stop_grace_period: 120s
     restart: always
@@ -110,7 +113,7 @@ services:
     network_mode: "${CELERY_SERVICE_NETWORK_MODE-service:openvpn}"
 
   celerybeat:
-    image: ${IMAGE_OWNER:-openwisp}/openwisp-dashboard:${OPENWISP_VERSION:-edge}
+    image: ${IMAGE_REGISTRY:-docker.io}/${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}/openwisp-dashboard:${OPENWISP_VERSION:-edge}
     restart: always
     environment:
       - MODULE_NAME=celerybeat
@@ -124,7 +127,7 @@ services:
       - dashboard
 
   nginx:
-    image: ${IMAGE_OWNER:-openwisp}/openwisp-nginx:${OPENWISP_VERSION:-edge}
+    image: ${IMAGE_REGISTRY:-docker.io}/${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}/openwisp-nginx:${OPENWISP_VERSION:-edge}
     restart: always
     build:
       context: images
@@ -151,7 +154,7 @@ services:
       - websocket
 
   freeradius:
-    image: ${IMAGE_OWNER:-openwisp}/openwisp-freeradius:${OPENWISP_VERSION:-edge}
+    image: ${IMAGE_REGISTRY:-docker.io}/${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}/openwisp-freeradius:${OPENWISP_VERSION:-edge}
     restart: always
     build:
       context: images
@@ -167,7 +170,7 @@ services:
       - dashboard
 
   postfix:
-    image: ${IMAGE_OWNER:-openwisp}/openwisp-postfix:${OPENWISP_VERSION:-edge}
+    image: ${IMAGE_REGISTRY:-docker.io}/${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}/openwisp-postfix:${OPENWISP_VERSION:-edge}
     restart: always
     build:
       context: images
@@ -178,7 +181,7 @@ services:
       - openwisp_certs:/etc/ssl/mail
 
   openvpn:
-    image: ${IMAGE_OWNER:-openwisp}/openwisp-openvpn:${OPENWISP_VERSION:-edge}
+    image: ${IMAGE_REGISTRY:-docker.io}/${IMAGE_NAMESPACE:-${IMAGE_OWNER:-openwisp}}/openwisp-openvpn:${OPENWISP_VERSION:-edge}
     restart: on-failure
     build:
       context: images

docs/developer/instructions.rst

@@ -132,10 +132,10 @@ Makefile Options
 
 Most commonly used:
 
-- ``make start [IMAGE_OWNER=docker-username] [OPENWISP_VERSION=version]``:
-  Start OpenWISP containers on your server.
-- ``make pull [IMAGE_OWNER=docker-username] [OPENWISP_VERSION=version]``:
-  Pull images from the registry.
+- ``make start [IMAGE_REGISTRY=registry] [IMAGE_NAMESPACE=namespace]
+  [OPENWISP_VERSION=version]``: Start OpenWISP containers on your server.
+- ``make pull [IMAGE_REGISTRY=registry] [IMAGE_NAMESPACE=namespace]
+  [OPENWISP_VERSION=version]``: Pull images from the registry.
 - ``make stop``: Stop OpenWISP containers on your server.
 - ``make develop``: Bundle all the commands required to build the images
   and run containers.
@@ -146,7 +146,7 @@ Most commonly used:
 
 Other options:
 
-- ``make publish [IMAGE_OWNER=docker-username]
+- ``make publish [IMAGE_REGISTRY=registry] [IMAGE_NAMESPACE=namespace]
   [OPENWISP_VERSION=version]``: Build, test, and publish images.
 - ``make python-build``: Generate a random Django secret and set it in the
   ``.env`` file.

docs/user/settings.rst

@@ -1146,13 +1146,34 @@ X509 Certificates
 Misc Services
 -------------
 
+``IMAGE_REGISTRY``
+~~~~~~~~~~~~~~~~~~
+
+- **Explanation:** Docker registry host for OpenWISP images. Change this
+  together with ``IMAGE_NAMESPACE`` when using a custom registry.
+- **Valid Values:** A valid Docker registry host.
+- **Default:** ``docker.io``.
+
+``IMAGE_NAMESPACE``
+~~~~~~~~~~~~~~~~~~~
+
+- **Explanation:** Docker repository namespace for OpenWISP images. Change
+  this if you're using a custom registry.
+- **Valid Values:** A valid Docker repository namespace or path.
+- **Default:** ``openwisp``.
+
 ``IMAGE_OWNER``
 ~~~~~~~~~~~~~~~
 
-- **Explanation:** Docker registry namespace for OpenWISP images. Change
-  this only if you are using custom-built images or a private registry.
-- **Valid Values:** A valid Docker registry namespace.
-- **Default:** ``openwisp``
+.. warning::
+
+    ``IMAGE_OWNER`` is deprecated and will be removed in the next major
+    release. Use ``IMAGE_NAMESPACE`` instead. Make commands emit a
+    deprecation warning when ``IMAGE_OWNER`` is set.
+
+- **Explanation:** Legacy Docker repository namespace. It is used only
+  when ``IMAGE_NAMESPACE`` is unset during the deprecation period.
+- **Valid Values:** A valid Docker repository namespace or path.
 
 ``REDIS_HOST``
 ~~~~~~~~~~~~~~

images/openwisp_api/Dockerfile

@@ -1,7 +1,8 @@
 # hadolint ignore=DL3007
-ARG IMAGE_OWNER=openwisp
+ARG IMAGE_REGISTRY=docker.io
+ARG IMAGE_NAMESPACE=openwisp
 ARG OPENWISP_VERSION=edge
-FROM ${IMAGE_OWNER}/openwisp-base:${OPENWISP_VERSION}
+FROM ${IMAGE_REGISTRY}/${IMAGE_NAMESPACE}/openwisp-base:${OPENWISP_VERSION}
 
 WORKDIR /opt/openwisp/
 

images/openwisp_dashboard/Dockerfile

@@ -1,7 +1,8 @@
 # hadolint ignore=DL3007
-ARG IMAGE_OWNER=openwisp
+ARG IMAGE_REGISTRY=docker.io
+ARG IMAGE_NAMESPACE=openwisp
 ARG OPENWISP_VERSION=edge
-FROM ${IMAGE_OWNER}/openwisp-base:${OPENWISP_VERSION}
+FROM ${IMAGE_REGISTRY}/${IMAGE_NAMESPACE}/openwisp-base:${OPENWISP_VERSION}
 WORKDIR /opt/openwisp/
 
 # Location: /opt/openwisp/

images/openwisp_websocket/Dockerfile

@@ -1,7 +1,8 @@
 # hadolint ignore=DL3007
-ARG IMAGE_OWNER=openwisp
+ARG IMAGE_REGISTRY=docker.io
+ARG IMAGE_NAMESPACE=openwisp
 ARG OPENWISP_VERSION=edge
-FROM ${IMAGE_OWNER}/openwisp-base:${OPENWISP_VERSION}
+FROM ${IMAGE_REGISTRY}/${IMAGE_NAMESPACE}/openwisp-base:${OPENWISP_VERSION}
 
 WORKDIR /opt/openwisp/