Set Swissmakers container-image to the new default, add comments abbout podman

2026-05-08 23:38:57 +02:00 · 2026-04-15 12:30:16 +02:00
parent f534426da5
commit 20d70110fa
8 changed files with 70 additions and 54 deletions
@@ -1,5 +1,5 @@
 # NetBox Plus on Red Hat Universal Base Image (UBI).
-# Build from repository root: docker build -t netbox-plus:local .
+# Build from repository root: podman build -t netbox-plus:dev .
 #
 # Default is UBI 9 so the image runs on older x86_64 CPUs. UBI 10 userspace
 # requires x86-64-v3; on capable hardware you can use:
@@ -16,21 +16,28 @@ On top of that, NetBox Plus will add Swissmakers improvements such as hardenings

 This repository includes a **Dockerfile** and **Compose** stack (PostgreSQL, Redis, Gunicorn, RQ workers) based on **Red Hat UBI** (UBI 9 by default; UBI 10 optional on capable CPUs). See `docker/` and `docker-compose.yml`.

+**Swissmakers recommends [Podman](https://podman.io/)** for this stack on Linux; examples use `podman compose`. See [Containers with Podman Compose](docs/installation/docker.md) for commands and why Podman is the documented default.
+
 ### Pre-built image (Swissmakers)

-Official multi-arch builds are published to Docker Hub as **[`swissmakers/netbox-plus`](https://hub.docker.com/repository/docker/swissmakers/netbox-plus)**. Pull with `docker pull swissmakers/netbox-plus:latest` (or another published tag), set `NETBOX_IMAGE=swissmakers/netbox-plus:latest` in `.env`, then from the repo root run `docker compose pull` and `docker compose up -d`. Details: [Docker / Compose install docs](docs/installation/docker.md).
+Official multi-arch builds are published to Docker Hub as **[`swissmakers/netbox-plus`](https://hub.docker.com/repository/docker/swissmakers/netbox-plus)**. From the repo root run `podman compose pull` and `podman compose up -d` (Compose defaults to that image; override `NETBOX_IMAGE` in `.env` for another tag or registry). More detail: [Containers with Podman Compose](docs/installation/docker.md) and `docker/README.md`.

 ### Build from source

+Build and tag a local development image directly from the repository root:
+
 ```bash
-cp docker/.env.example .env
-# Edit .env —> set NETBOX_SECRET_KEY and change superuser variables
-docker compose up --build
-# UI: http://localhost:8080
+podman build -t netbox-plus:dev .
 ```

-Adjust for your orchestrator (e.g. Podman) as needed.
+Then set `NETBOX_IMAGE=localhost/netbox-plus:dev` in `.env` and start the stack:

+```bash
+cp docker/.env.example .env
+# Edit .env —> set NETBOX_SECRET_KEY and NETBOX_IMAGE=localhost/netbox-plus:dev
+podman compose up -d
+# UI: http://localhost:8080
+```

 ## Documentation

@@ -2,13 +2,13 @@
 #
 # Usage:
 #   cp docker/.env.example .env
-#   # Edit .env —> set NETBOX_SECRET_KEY and optional superuser vars
-#   docker compose up --build
+#   # Edit .env —> set NETBOX_SECRET_KEY (and NETBOX_IMAGE if not using the default)
+#   podman compose pull && podman compose up -d
 #
 # UI: http://localhost:8080
 #
-# Pre-built image: set NETBOX_IMAGE=swissmakers/netbox-plus:latest in .env, then
-#   podman compose pull && podman compose up -d
+# Default image is a pre-built NetBox Plus image on Docker Hub. Override NETBOX_IMAGE in .env if needed.
+# To use a local build instead, run `podman build -t netbox-plus:dev .` and set `NETBOX_IMAGE=localhost/netbox-plus:dev`.
 #   https://hub.docker.com/repository/docker/swissmakers/netbox-plus
 #
 services:
@@ -42,13 +42,7 @@ services:
      start_period: 5s

  netbox:
-    build:
-      context: .
-      dockerfile: Dockerfile
-      args:
-        # UBI 10 needs x86-64-v3; UBI 9 is the default to also support older CPUs (see docker/README.md).
-        BASE_IMAGE: ${NETBOX_BASE_IMAGE:-registry.access.redhat.com/ubi9/ubi:latest}
-    image: ${NETBOX_IMAGE:-netbox-plus:local}
+    image: ${NETBOX_IMAGE:-swissmakers/netbox-plus:latest}
    restart: unless-stopped
    depends_on:
      postgres:
@@ -97,7 +91,7 @@ services:
      start_period: 180s

  netbox-worker:
-    image: ${NETBOX_IMAGE:-netbox-plus:local}
+    image: ${NETBOX_IMAGE:-swissmakers/netbox-plus:latest}
    restart: unless-stopped
    depends_on:
      postgres:
@@ -1,4 +1,4 @@
-# Copy to project root as `.env` for docker compose:
+# Copy to project root as `.env` for podman compose:
 #   cp docker/.env.example .env

 # Required: at least 50 random characters for production
@@ -31,8 +31,10 @@ NETBOX_PUBLISH_PORT=8080
 # Django DEBUG (never enable in production). Compose passes NETBOX_DEBUG to the web container.
 # NETBOX_DEBUG=true

-# NetBox app image: default uses local build tag, to set the Swissmakers pre-built from Docker Hub uncomment:
-#   NETBOX_IMAGE=swissmakers/netbox-plus:latest
+# NetBox app image: default swissmakers/netbox-plus:latest.
+# For local builds, set NETBOX_IMAGE=localhost/netbox-plus:dev after running:
+#   podman build -t netbox-plus:dev .
+#   NETBOX_IMAGE=registry.example.com/netbox/netbox-plus:1.2.3

-# Optional: To use UBI 10 on newer hosts with x86-64-v3 uncomment (otherwise it will use UBI 9)
+# Optional: for local podman build on x86-64-v3-capable hosts only:
 #   NETBOX_BASE_IMAGE=registry.access.redhat.com/ubi10/ubi:latest
@@ -1,37 +1,45 @@
-# Docker / Compose (NetBox Plus)
+# Podman Compose (NetBox Plus)

 This stack uses:

 - **Dockerfile**: default `registry.access.redhat.com/ubi9/ubi:latest` (UBI 9) with Python 3.12, dependencies from `requirements.txt`, and Gunicorn. UBI 10 is optional via build-arg (see below).
 - **docker-compose.yml**: PostgreSQL 16, Redis 7, NetBox web (Gunicorn), and NetBox RQ worker (`high`, `default`, `low` queues).

+**Swissmakers recommends [Podman](https://podman.io/)** for building and running this stack on Linux (daemonless, rootless-friendly, strong fit with RHEL and UBI). Examples below use `podman compose`. For rationale, see **[Containers with Podman Compose](../docs/installation/docker.md)** in the docs (or the rendered install guide). If your site uses Docker Engine, substitute `docker compose` for the same files.
+
 ## Pre-built image (Swissmakers / Docker Hub)

 Swissmakers publishes ready-to-use images to Docker Hub:

 **[hub.docker.com — `swissmakers/netbox-plus`](https://hub.docker.com/repository/docker/swissmakers/netbox-plus)**

-Use them with this Compose file by setting in `.env`:
+The main `docker-compose.yml` uses that image by default (`image: swissmakers/netbox-plus:latest`). Override `NETBOX_IMAGE` in `.env` only for another tag, a private registry, or a local dev image.

-```env
-NETBOX_IMAGE=swissmakers/netbox-plus:latest
-```
-
-Then from the repository root:
+From the repository root:

 ```bash
-docker compose pull netbox
-docker compose up -d
+podman compose pull netbox
+podman compose up -d
 ```

-Use `docker compose up --build` when you want to **build** from the local `Dockerfile` instead of using the registry image.
+To **build** from the local `Dockerfile` instead of pulling, build an image locally and point Compose at it via `NETBOX_IMAGE`.

-## Quick start (build locally)
+```bash
+podman build -t netbox-plus:dev .
+```
+
+Then set `NETBOX_IMAGE=localhost/netbox-plus:dev` in `.env` and run:
+
+```bash
+podman compose up -d
+```
+
+## Quick start (pre-built image)

 ```bash
 cp docker/.env.example .env
 # Edit .env —> set NETBOX_SECRET_KEY (and optionally superuser + password)
-docker compose up --build
+podman compose pull && podman compose up -d
 ```

 Open `http://localhost:8080`. To create an admin on first boot:
@@ -49,12 +57,10 @@ Runtime settings are driven by `docker/configuration_docker.py` (copied into the

 ## Notes

- **CPU / glibc (x86-64-v3)**: UBI **10** glibc is built for **x86-64-v3**. Older CPUs hit `Fatal glibc error: CPU does not support x86-64-v3` during `RUN dnf`. The default **UBI 9** base avoids that. To build on UBI 10 anyway (v3-capable CPU only):
-  `podman build --build-arg BASE_IMAGE=registry.access.redhat.com/ubi10/ubi:latest -t netbox-plus:local .`
-  or set `NETBOX_BASE_IMAGE` in Compose (see `docker-compose.yml` `build.args`).
+- **CPU / glibc (x86-64-v3)**: UBI **10** glibc is built for **x86-64-v3**. Older CPUs hit `Fatal glibc error: CPU does not support x86-64-v3` during `RUN dnf`. The default **UBI 9** base avoids that. To build on UBI 10 anyway (v3-capable CPU only), set `NETBOX_BASE_IMAGE=registry.access.redhat.com/ubi10/ubi:latest` and run `podman build -t netbox-plus:dev .`.
 - **Housekeeping** (scheduled jobs) is not included; add a cron sidecar or host job if you need it in production.
 - For TLS termination, place a reverse proxy in front and set `NETBOX_CSRF_TRUSTED_ORIGINS` / `NETBOX_ALLOWED_HOSTS` accordingly.
 - **Migrations**: only the `netbox` (web) service runs `migrate`; `netbox-worker` waits for `netbox` to be healthy so two containers never migrate in parallel (that caused `django_migrations` / `pg_type` conflicts on first boot).
 - **Postgres / `core_configrevision` during `migrate`**: the entrypoint sets `NETBOX_SKIP_DB_CONFIG=1` for `migrate` only so NetBox does not query `ConfigRevision` before that table exists (avoids spurious `ERROR: relation ... does not exist` in Postgres logs). Gunicorn and the worker run without that flag so dynamic config loads normally.
- If a previous attempt left Postgres half-initialized, reset the DB volume: `podman compose down -v` (removes `postgres-data`) then `up --build` again.
+- If a previous attempt left Postgres half-initialized, reset the DB volume: `podman compose down -v` (removes `postgres-data`) then `pull` and `up -d` again (or rebuild with `podman build`).
 - The UBI image pulls unauthenticated from `registry.access.redhat.com`; ensure your registry policy allows it.
@@ -1,7 +1,19 @@
-# Docker / Compose (NetBox Plus)
+# Containers with Podman Compose (NetBox Plus)

 NetBox Plus ships a **Dockerfile** and **Compose** stack in the repository root: PostgreSQL 16, Redis 7, Gunicorn (web), and RQ workers. The image is based on **Red Hat UBI** (UBI 9 by default; UBI 10 optional on CPUs that support x86-64-v3).

+Documentation and examples use **`podman`** and **`podman compose`**. If your organization standardizes on Docker Engine, the same `docker-compose.yml` works with **`docker compose`**; only the CLI prefix changes.
+
+## Why we recommend Podman
+
+- **Daemonless model:** Podman runs containers as regular processes instead of relying on a single long-lived root daemon for every operation. That simplifies threat modeling and avoids the “access to the Docker socket” pattern that is effectively broad host privilege on many setups.
+- **Rootless-first:** Building and running images as an unprivileged user is a well-supported path, which matters on shared servers and in regulated environments.
+- **Same images and workflows:** Podman uses **OCI** images and registries like Docker Hub; commands mirror Docker’s (`podman run`, `podman build`, `podman compose`).
+- **Alignment with RHEL / UBI:** The NetBox Plus image is built on **Red Hat UBI**; Podman is the supported container stack on RHEL and integrates cleanly with **SELinux** and enterprise Linux policies.
+- **Licensing on workstations:** **Docker Desktop** has commercial licensing constraints for some companies; **Podman Desktop** is a practical alternative where that applies.
+
+Some tools still assume a Docker socket; if you depend on those, Docker may remain the right choice for that environment. For typical NetBox Plus deployments on Linux, **Podman is the default we document and recommend**.
+
 ## Official pre-built image

 Swissmakers publishes a ready-to-use image to Docker Hub:
@@ -11,27 +23,21 @@ Swissmakers publishes a ready-to-use image to Docker Hub:
 Pull the latest tag (or a specific tag if published):

 ```bash
-docker pull swissmakers/netbox-plus:latest
+podman pull swissmakers/netbox-plus:latest
 ```

-Use it with the bundled Compose file:
+Use it with the bundled Compose file (the default `image` is `swissmakers/netbox-plus:latest`; set `NETBOX_IMAGE` in `.env` only for another tag or registry):

 1. Copy the environment template: `cp docker/.env.example .env`
 2. Set at least `NETBOX_SECRET_KEY`, change admin credentials and modify any host/CSRF values you need.
-3. Point Compose at the registry image in `.env` like:
-
-   ```env
-   NETBOX_IMAGE=swissmakers/netbox-plus:latest
-   ```
-
-4. From the **repository root** (where `docker-compose.yml` lives):
+3. From the **repository root** (where `docker-compose.yml` lives):

   ```bash
   podman compose pull netbox
   podman compose up -d
   ```

-After the image is present locally, Compose will use it for both `netbox` and `netbox-worker`. Use `docker compose up --build` only when you intend to **build** the image from the local `Dockerfile` instead of using the pre-built one.
+After the image is present locally, Compose will use it for both `netbox` and `netbox-worker`. The main Compose file does **not** define `build:` for `netbox` (so `NETBOX_IMAGE` is not ignored by an automatic rebuild). To build from the local `Dockerfile`, run `podman build` and set `NETBOX_IMAGE=localhost/netbox-plus:dev` in `.env` (see `docker/README.md`).

 Open the UI on `http://localhost:8080` (or the host/port you mapped with `NETBOX_PUBLISH_PORT`).

@@ -40,9 +46,10 @@ Open the UI on `http://localhost:8080` (or the host/port you mapped with `NETBOX
 To build the UBI image locally (same layout as CI):

 ```bash
+podman build -t netbox-plus:dev .
 cp docker/.env.example .env
-# edit .env — set NETBOX_SECRET_KEY, superuser vars, etc.
-docker compose up --build
+# edit .env — set NETBOX_SECRET_KEY, superuser vars, and NETBOX_IMAGE=localhost/netbox-plus:dev
+podman compose up -d
 ```

 Optional: `NETBOX_BASE_IMAGE` for UBI 10 (see repository `docker/README.md`).
@@ -2,7 +2,7 @@

 The installation instructions provided here have been tested to work on Rocky Linux 10. The particular commands needed to install dependencies on other distributions may vary significantly. Unfortunately, this is outside the control of the NetBox maintainers. Please consult your distribution's documentation for assistance with any errors.

-For **NetBox Plus** using containers, Swissmakers provides an official image on Docker Hub and a Compose stack in the repository. See **[Docker / Compose (NetBox Plus)](docker.md)** for the pre-built image, pull commands, and how to set `NETBOX_IMAGE`.
+For **NetBox Plus** using containers, Swissmakers provides an official image on Docker Hub and a Compose stack in the repository. See **[Containers with Podman Compose (NetBox Plus)](docker.md)** for the pre-built image, `podman compose` commands, why Podman is recommended, and how to set `NETBOX_IMAGE`.

 The following sections detail how to set up a new instance of NetBox on a Linux host (traditional install):

@@ -93,7 +93,7 @@ nav:
        - Customization: 'features/customization.md'
    - Installation & Upgrade:
        - Installing NetBox: 'installation/index.md'
-        - Docker/Podman Compose (NetBox Plus): 'installation/docker.md'
+        - Podman Compose (NetBox Plus): 'installation/docker.md'
        - 1. PostgreSQL: 'installation/1-postgresql.md'
        - 2. Redis: 'installation/2-redis.md'
        - 3. NetBox: 'installation/3-netbox.md'