Netbox upgrade from 4.0.2. to 5.0.0

[XaratosS]

Current Behavior

I want to upgrade netbox docker 4.0.2 to netbox docker 5.0.0 but the minimum requirement to upgrade it is netbox version 4.6.x but with 4.0.2 you only get Netbox version 4.5.10. So an upgrade is not possible. We are also running it as a docker swarm so it is slightly modified.

Expected Behavior

A working upgrade path is expected.
Netbox Discussion

Docker Compose Version

Docker Compose Version 5.1.4

Docker Version

Client: Docker Engine - Community
 Version:           29.5.2
 API version:       1.54
 Go version:        go1.26.3
 Git commit:        79eb04c
 Built:             Wed May 20 14:38:09 2026
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          29.5.2
  API version:      1.54 (minimum version 1.40)
  Go version:       go1.26.3
  Git commit:       568f755
  Built:            Wed May 20 14:38:09 2026
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v2.2.4
  GitCommit:        193637f7ee8ae5f5aa5248f49e7baa3e6164966e
 runc:
  Version:          1.3.5
  GitCommit:        v1.3.5-0-g488fc13e
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

The git Revision

a89729a4bff994f268133e647363a69b143a3784

The git Status

git status
On branch test
Your branch is up to date with 'origin/test'.

Startup Command

docker stack deploy --compose-file docker-compose.yml netbox-dev

NetBox Logs

nothing noteworthy here

Content of docker-compose.override.yml

services:
  netbox:
    image: ghcr.io/CUSTOM_REGISTRY:${IMAGE_TAG}
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints: [node.role == worker]
    env_file: .env
    user: "netbox:root"
    healthcheck:
      test: curl -f http://localhost:8080/login/ || exit 1
      start_period: 90s
      timeout: 3s
      interval: 15s
    ports:
      - "50011:8080"
    volumes:
      - netbox-config:/etc/netbox/config
      - netbox-media-files:/opt/netbox/netbox/media
      - netbox-reports-files:/opt/netbox/netbox/reports
      - netbox-scripts-files:/opt/netbox/netbox/scripts
      - netbox-static-files:/opt/netbox/netbox/static
    networks:
      - netbox_network
  # netbox worker
  netbox-worker:
    image: ghcr.io/CUSTOM_REGISTRY:${IMAGE_TAG}
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints: [node.role == worker]
    command:
      - /opt/netbox/venv/bin/python
      - /opt/netbox/netbox/manage.py
      - rqworker
    healthcheck:
      test: ps -aux | grep -v grep | grep -q rqworker || exit 1
      start_period: 20s
      timeout: 3s
      interval: 15s
    env_file: .env
    volumes:
      - netbox-scripts-files:/opt/netbox/netbox/scripts
    networks:
      - netbox_network
  # postgres
  postgres:
    image: docker.io/postgres:18-alpine
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints: [node.role == worker]
    healthcheck:
      test: pg_isready -q -t 2 -d $$POSTGRES_DB -U $$POSTGRES_USER
      start_period: 20s
      timeout: 30s
      interval: 10s
      retries: 5
    env_file: .env
    networks:
      - netbox_network
    volumes:
      - netbox-postgres-data:/var/lib/postgresql/data
  # redis
  redis:
    image: docker.io/valkey/valkey:9.0-alpine
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints: [node.role == worker]
    command:
      - sh
      - -c # this is to evaluate the $REDIS_PASSWORD from the env
      - valkey-server --appendonly yes --requirepass $$REDIS_PASSWORD ## $$ because of docker-compose
    healthcheck: &redis-healthcheck
      test: '[ $$(valkey-cli --pass "$${REDIS_PASSWORD}" ping) = ''PONG'' ]'
      start_period: 5s
      timeout: 3s
      interval: 1s
      retries: 5
    env_file: .env
    networks:
      - netbox_network
    volumes:
      - netbox-redis-data:/data

networks:
  netbox_network:
    driver: overlay
volumes:
  netbox-media-files:
    driver_opts:
      type: "nfs"
      o: "addr=10.60.30.13,nolock,hard,rw"
      device: ":/v_nfs_docker_clu01_03_01/docker_dev/netbox.dev.bvb.ch/netbox-media-files/"
  netbox-postgres-data:
    driver_opts:
      type: "nfs"
      o: "addr=10.60.30.13,nolock,hard,rw"
      device: ":/v_nfs_docker_clu01_03_01/docker_dev/netbox.dev/netbox-postgres-18-data/"
  netbox-redis-data:
    driver_opts:
      type: "nfs"
      o: "addr=10.60.30.13,nolock,hard,rw"
      device: ":/v_nfs_docker_clu01_03_01/docker_dev/netbox.dev/netbox-redis-data/"
  netbox-reports-files:
    driver_opts:
      type: "nfs"
      o: "addr=10.60.30.13,nolock,hard,rw"
      device: ":/v_nfs_docker_clu01_03_01/docker_dev/netbox.dev/netbox-reports-files/"
  netbox-scripts-files:
    driver_opts:
      type: "nfs"
      o: "addr=10.60.30.13,nolock,hard,rw"
      device: ":/v_nfs_docker_clu01_03_01/docker_dev/netbox.dev/netbox-scripts-files/"
  netbox-config:
    driver_opts:
      type: "nfs"
      o: "addr=10.60.30.13,nolock,hard,rw"
      device: ":/v_nfs_docker_clu01_03_01/docker_dev/netbox.dev/netbox-config/"
  netbox-static-files:
    driver_opts:
      type: "nfs"
      o: "addr=10.60.30.13,nolock,hard,rw"
      device: ":/v_nfs_docker_clu01_03_01/docker_dev/netbox.dev/netbox-static-files/"

[tinyhare]

I just upgraded directly and it went smoothly.

docker compose down
git fetch --tags
git merge 5.0.0
git diff HEAD^ HEAD    # to see what changed
docker compose up    # no -d parameter，to watch the progress

The database migrations：

At last，healthy check done：

Don’t forget to daemonize it.

docker compose up -d

[XaratosS]

I will test it on the dev environment and see if it works without any issues.