Nautobot Docker

Installing Nautobot 3.1 using Docker should be straightforward — but if you use the official nautobot-docker-compose repository, there are several non‑obvious pitfalls that can easily derail you.

This guide documents a fully working Nautobot 3.1 Docker installation and highlights every issue you are likely to encounter, why it happens, and how to fix it.

If you follow this post end‑to‑end, you will have:

• A healthy Nautobot 3.1 deployment
• A locally accessible web UI
• A production‑correct Docker layout
• Zero DisallowedHost errors

What You’ll End Up With

• Nautobot 3.1
• Python 3.11
• Django 4.2
• PostgreSQL 14
• Redis
• Celery worker + beat
• No local Docker builds
• Correct port exposure
• Fully accessible UI at http://localhost:8080

Prerequisites

• Docker Desktop (macOS, Linux, or Windows)
• Docker Compose v2
• Git

Verify Docker:

docker version

docker compose version

1. Clone the Official Repository

git clone https://github.com/nautobot/nautobot-docker-compose.git

cd nautobot-docker-compose

Important:
This repository does not contain a default docker-compose.yml.
Every Docker command must explicitly pass the required compose files.

2. Use a Supported PostgreSQL Version (Critical)

The Problem

You will see this error if you use PostgreSQL 13 or earlier:

django.db.utils.NotSupportedError:
PostgreSQL 14 or later is required

Why This Happens

Nautobot 3.x requires PostgreSQL 14 or newer.
The default compose file still references PostgreSQL 13.

The Fix

environments/docker-compose.postgres.yml

Change:

image: postgres:13-alpine

To:

image: postgres:14-alpine

3. Disable the Local “Dev” Image Build

The Problem

You may see errors like:

yourrepo/nautobot-docker-compose:local

invalid reference format ghcr.io/nautobot/nautobot-dev:-py

Why This Happens

The repository supports both development and production workflows.
If you don’t override it, Docker will always try to build a local image.

The Fix: Production Image Override

Create the file:

environments/docker-compose.override.prod.yml

add the following to the file

services:

  nautobot:

    image: ghcr.io/nautobot/nautobot:3.1.0-py3.11

  celery_worker:

    image: ghcr.io/nautobot/nautobot:3.1.0-py3.11

  celery_beat:

    image: ghcr.io/nautobot/nautobot:3.1.0-py3.11

This completely disables local builds and forces official images.

4. Expose Ports to the Host

The Problem

Everything looks healthy, but:

curl http://localhost:8080

Connection refused

Why This Happens

The default compose files use expose, not ports.
This allows container‑to‑container traffic only.

The Fix: Port Override

Create:

environments/docker-compose.override.ports.yml

add the following:

services:

  nautobot:

    ports:

      - "8080:8080"

      - "8443:8443"

5. Start Nautobot

docker compose 

  -f environments/docker-compose.base.yml 

  -f environments/docker-compose.postgres.yml

  -f environments/docker-compose.override.prod.yml 

  -f environments/docker-compose.override.ports.yml 

  up -d

Verify:

docker compose 

  -f environments/docker-compose.base.yml 

  -f environments/docker-compose.postgres.yml 

  -f environments/docker-compose.override.prod.yml 

  -f environments/docker-compose.override.ports.yml 

  ps

You should see:

0.0.0.0:8080->8080/tcp

6. Fix the DisallowedHost Error

The Error

DisallowedHost at /

Invalid HTTP_HOST header: ‘localhost:8080’

Why This Happens

Nautobot runs on Django, which enforces:

• ALLOWED_HOSTS
• CSRF_TRUSTED_ORIGINS (required in Django 4.2+)

Environment variables alone are unreliable with this compose layout.

The Fix

Modify Nautobot’s configuration file inside the container.

Allow localhost:

docker compose 

  -f environments/docker-compose.base.yml 

  -f environments/docker-compose.postgres.yml 

  -f environments/docker-compose.override.prod.yml 

  -f environments/docker-compose.override.ports.yml 

  exec nautobot 

  sed -i 

  "s|^# ALLOWED_HOSTS.*|ALLOWED_HOSTS = ['localhost','127.0.0.1','[::1]']|" 

  /opt/nautobot/nautobot_config.py

Note: if not accessing Nautobot locally you can add your allowed hosts in here instead of just localhost

Allow CSRF origins:

docker compose 

  -f environments/docker-compose.base.yml 

  -f environments/docker-compose.postgres.yml 

  -f environments/docker-compose.override.prod.yml 

  -f environments/docker-compose.override.ports.yml 

  exec nautobot 

  sed -i 

  "s|^# CSRF_TRUSTED_ORIGINS.*|CSRF_TRUSTED_ORIGINS = ['http://localhost:8080','http://127.0.0.1:8080']|" 

  /opt/nautobot/nautobot_config.py

Restart Nautobot:

docker compose 

  -f environments/docker-compose.base.yml 

  -f environments/docker-compose.postgres.yml

  -f environments/docker-compose.override.prod.yml

  -f environments/docker-compose.override.ports.yml 

  restart nautobot

7. Access Nautobot

Open your browser:

http://localhost:8080

8. Create Superuser

docker compose \
  -f environments/docker-compose.base.yml \
  -f environments/docker-compose.postgres.yml \
  -f environments/docker-compose.override.prod.yml \
  -f environments/docker-compose.override.ports.yml \
  exec nautobot \
  nautobot-server createsuperuser \
  --config-path /opt/nautobot/nautobot_config.py

You will be prompted to enter username/email & password

You can then login with these credentials.

Common Problems and Fixes

Final Thoughts

Nautobot itself is solid — the complexity lies in the flexibility of the Docker Compose repository. Once you understand:

• Dev vs prod images
• Expose vs publish ports
• Django host and CSRF security

…everything falls into place.

With the overrides described above, Nautobot 3.1 runs cleanly, securely, and predictably.

Related Posts

How to install Nautobot on Ubuntu Server