Docker development¶
The shared development stack installs Nautobot Agent in editable mode alongside
Nautobot 3.2.6, Python 3.12, PostgreSQL 17, Redis 7, and Celery
worker and scheduler services. Python dependencies come from poetry.lock.
Requirements¶
- Git.
- Docker Engine with Docker Compose v2 or newer, or Docker Desktop.
- Linux containers. On Windows 11, use Docker Desktop's WSL 2 backend.
The commands below work from PowerShell, macOS terminals, and Linux shells. No host Python, Poetry, Node.js, database, or Redis installation is required. On Windows, a checkout inside the WSL filesystem generally gives faster bind mounts than a Windows drive. Allow Docker Desktop access to the checkout if prompted.
Start¶
Clone the repository and enter its root directory. Copy
development/nautobot_config.example.py to development/nautobot_config.py
once:
=== "PowerShell"
```powershell
Copy-Item development/nautobot_config.example.py development/nautobot_config.py
```
=== "macOS / Linux"
```shell
cp development/nautobot_config.example.py development/nautobot_config.py
```
The local copy is ignored by Git. Edit it to try deployment settings without
changing the shared example. Keep provider secrets in the ignored root .env.
Do not overwrite an existing local configuration when updating the checkout;
consult the example for new settings. Omitted plugin settings use app defaults.
Then run:
docker compose up
Compose builds the development image on first use. Initial dependency downloads and database migrations can take several minutes. The web container runs Nautobot's initialization, including migrations and static-file collection; workers start after Nautobot passes its health check.
Compose mounts the local configuration read-only into web, worker, and beat
containers and refuses to create a missing source path. If startup reports a
missing development/nautobot_config.py, copy the example first. Image builds
use only the tracked example; the local configuration is not a build input.
Open http://localhost:8080 and sign in with username admin, password
admin. To run in the background instead, use docker compose up -d.
Local development only
This stack uses public, disposable database credentials, a fixed secret key,
and an administrator API token of
0123456789abcdef0123456789abcdef01234567. Initialization resets the admin
password to admin on web-container startup. Debug mode is enabled and the
development server is bound to host loopback only. Do not deploy this
configuration, expose it through a public proxy, or load production data.
PostgreSQL and Redis have no published host ports.
The app is enabled automatically. To configure provider credentials, see
Provider credentials, then follow
Getting started to configure an LLM.
Provider traffic leaves the containers; review
Privacy and data handling before using real data.
For host-based services such as Ollama, localhost inside a container is the
container itself. Docker Desktop provides host.docker.internal; on Linux,
configure an appropriate reachable host address.
If port 8080 is occupied, create a root .env containing NAUTOBOT_PORT=8081
and open port 8081 instead. This file is ignored by Git; do not put private
credentials in tracked development files.
Provider credentials¶
Put your provider keys in the ignored .env at the repository root. Keep only
the providers you use; no keys are required to start the stack.
OPENAI_API_KEY=replace-with-your-key
ANTHROPIC_API_KEY=replace-with-your-key
GOOGLE_API_KEY=replace-with-your-key
OPENROUTER_API_KEY=replace-with-your-key
DEEPSEEK_API_KEY=replace-with-your-key
# Optional, for Ollama running on a Docker Desktop host:
OLLAMA_BASE_URL=http://host.docker.internal:11434
Compose automatically reads this file before creating containers. Exported shell
variables take precedence over .env values. Only the listed provider variables
are forwarded to the app services; the file is not mounted or included in the
image. Do not commit it or put keys in development/development.env.
The development configuration creates these profiles for nonempty variables:
| Provider | Environment variable | Credential profile |
|---|---|---|
| OpenAI | OPENAI_API_KEY |
openai |
| Anthropic | ANTHROPIC_API_KEY |
anthropic |
Google Gemini (google_genai) |
GOOGLE_API_KEY |
google |
| OpenRouter | OPENROUTER_API_KEY |
openrouter |
| DeepSeek | DEEPSEEK_API_KEY |
deepseek |
| Ollama | OLLAMA_BASE_URL |
ollama |
Select the corresponding credential profile when creating an LLM configuration.
Ollama does not require a key; without OLLAMA_BASE_URL, leave its credential
profile blank and supply a reachable base_url in the LLM's Parameters.
This does not create model configurations or choose a default Agent model.
After changing .env, run docker compose up -d to recreate containers with
the updated values. docker compose restart does not reload their environment.
No image rebuild is required.
Environment values are sensitive
Docker administrators can inspect container environment variables.
docker compose config also expands the keys; do not share its output.
Use docker compose config --quiet to validate without printing them.
Edit and run checks¶
The app, browser tests, documentation, and shared tooling files are mounted individually. The entire checkout is never mounted. The image build also uses an explicit allowlist of project inputs rather than sending the whole checkout.
Python web changes reload automatically; refresh the browser for frontend
changes. Worker and beat use watchmedo to restart automatically when Python
files change in the app or Nautobot configuration directories. The watchers use
polling to support Docker Desktop bind mounts on Windows and macOS as well as
Linux. Editing code can interrupt active development chat runs.
Web and worker logging defaults to DEBUG; beat defaults to INFO. Override
NAUTOBOT_LOG_LEVEL or NAUTOBOT_BEAT_LOG_LEVEL in the root .env and run
docker compose up -d to apply different levels.
Edit files with your usual local editor. Run checks from your host terminal; you do not need to open a shell or editor inside the container:
docker compose exec -T nautobot invoke unittest --no-input
docker compose exec -T nautobot invoke unittest --no-input --label nautobot_agent.tests.test_run_smoke
docker compose exec -T nautobot sh -c 'node --test tests/*.test.cjs'
docker compose exec -T nautobot invoke tests --no-input
docker compose exec -T nautobot invoke build-and-check-docs
Each command starts a separate process and returns its output and exit status
to your terminal; it does not restart the web server. Local linting and type
checking remain available through a host Python environment with the project
development dependencies installed. The full invoke tests gate also runs
static checks inside Docker.
The image includes Node.js and Chromium for the browser suite, as well as Python development and documentation dependencies. Test databases live in the development PostgreSQL service, separately from the app database, and are reused between runs. Do not run concurrent Django test suites against the same test database. Keep the PostgreSQL volume to avoid repeating initial migrations.
Continuous integration¶
GitHub CI reuses this Compose stack and its locked dependencies. One job builds
the development image after copying the example configuration, starts
PostgreSQL and Redis, then runs invoke lock
--check, invoke tests --no-input, and invoke build-and-check-docs inside a
one-off app container. It does not start the web server, worker, or beat and
does not need provider keys.
The existing invoke tests task owns the check sequence: Ruff formatting and
linting, ty, djlint, Markdown linting, migration checks, Pylint, browser tests,
Django tests, and coverage reports. CI does not maintain a second list of lint
commands or regenerate the committed lockfile.
The workflow runs for pull requests, pushes to main and develop, and manual
dispatches. It tests the pinned Docker baseline,
not every Python/Nautobot combination allowed by the package metadata. It does
not build distribution packages or publish releases.
Dependency and schema changes¶
After changing dependencies, update poetry.lock using Poetry and rebuild:
docker compose up --build
The mounted dependency files are read-only inside containers. Keep the Nautobot
version in poetry.lock, development/Dockerfile, and the Compose image tag
aligned when changing the supported development baseline.
After adding migrations, stop the stack and start it again so initialization applies them before the workers start:
docker compose down
docker compose up
Logs and shutdown¶
docker compose ps
docker compose logs -f nautobot worker
docker compose down