VPS Tutorials
NetBox on a VPS: inventory, Docker, HTTPS and recovery
Deploy NetBox with a matching Docker template, private database and queues. Configure inventory, object permissions, tokens, SMTP and tested database/file recovery.

NetBox models sites, tenants, racks, devices, interfaces, VLANs, address prefixes and change history through a common UI and API. It can replace scattered spreadsheets for a lab, offices, VPS infrastructure or a network team. It records intended infrastructure; it does not automatically discover or enforce every device configuration.
This Ubuntu 24.04 and Docker guide covers the database, Redis-compatible queues/cache, HTTPS, permissions, background work and recovery. Start on a test hostname before putting real inventory into the service.
| Scope | CPU | RAM | Disk | Planning note |
|---|---|---|---|---|
| Personal lab | 2 vCPU | 4 GB | 40 GB SSD | Few devices; limit plugins |
| Small team | 4 vCPU | 8 GB | 80 GB NVMe | SMTP and independent backups |
| Multiple sites | 4-8 vCPU | 16 GB+ | 160 GB NVMe+ | Monitor growth; consider a separate database |
Use netbox.example.com with correct A/AAAA records. Keep database 5432 and cache 6379 private. Include logs, media and backups in capacity planning; these figures are estimates, not guarantees.
sudo apt update
sudo apt install -y ca-certificates curl git openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
sudo mkdir -p /opt/netbox
sudo chown -R "$USER":"$USER" /opt/netbox
cd /opt/netbox
Review the privileged installer or use supported repository packages. Avoid latest; pin compatible application, database, cache and plugin versions, recording digests.
git clone https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
cp env/netbox.env .env
Complete the template selection before starting. Select a reviewed netbox-docker release commit and inspect ls and git log -1. The release template reviewed on November 16, 2026 uses NetBox v4.7-5.1.2, PostgreSQL 18 and separate Valkey queue/cache services under the familiar redis names. Keep that release's complete configuration and storage layout rather than mixing older snippets with newer images. See netbox-docker.
The copied .env is not automatically the application's env_file. The official template reads env/netbox.env, env/postgres.env, env/redis.env and env/redis-cache.env. Edit those actual files. Compose's root .env primarily interpolates image VERSION and other template variables. Keep every secret file private and out of Git.
The original application-setting sketch is:
DB_NAME=netbox
DB_USER=netbox
DB_PASSWORD=change-a-long-database-password
REDIS_PASSWORD=change-a-long-redis-password
SECRET_KEY=replace-with-a-random-secret-key
SUPERUSER_NAME=admin
[email protected]
SUPERUSER_PASSWORD=change-a-long-admin-password
Generate independent random values:
openssl rand -base64 48
openssl rand -hex 32
chmod 600 .env
Set matching DB_PASSWORD/POSTGRES_PASSWORD in the application/database env files, matching REDIS_PASSWORD in application/queue files, and a different matching REDIS_CACHE_PASSWORD/REDIS_PASSWORD pair for redis-cache. Replace SECRET_KEY and the current release's API token pepper defaults with stable private values. Set the actual allowed hostname, trusted HTTPS origin and restrictive CORS behavior. Do not keep shipped passwords or a globally permissive CORS setting. Use interactive createsuperuser below; the current sample has SKIP_SUPERUSER=true, so merely entering SUPERUSER variables will not create an administrator.
Add a root docker-compose.override.yml with a loopback publication for the host Caddy:
services:
netbox:
ports:
- "127.0.0.1:8080:8080"
The upstream example publishes 8000 broadly; do not copy it unchanged while configuring a proxy on 8080. Pin all images in your chosen configuration and verify its actual merged output before:
docker compose config
docker compose pull
docker compose up -d
docker compose ps
Rendered configuration may contain secrets: inspect privately, or use config --quiet for syntax alone. Allow PostgreSQL initialization and migrations to finish; inspect netbox, netbox-worker, netbox-housekeeping if present, postgres and redis:
docker compose logs --tail=200 netbox
docker compose logs --tail=200 netbox-worker
docker compose logs --tail=200 postgres
For repeated restarts, inspect the actual env files, not only .env, and verify SECRET_KEY. Preserve volumes while diagnosing.
docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser
docker compose exec netbox /opt/netbox/netbox/manage.py check
- Create sites for datacenters, offices and cloud regions.
- Create tenants to label customer/department ownership; tenant labels alone do not enforce access isolation.
- Define manufacturers, device types, roles and platforms consistently.
- Model prefixes, IP ranges, VLANs and VRFs with clear ownership.
- Add racks, devices, interfaces, links and power relationships.
Map a single site's existing data first. Verify relationships before importing the full CSV or API inventory.
sudo apt install -y caddy
sudo nano /etc/caddy/Caddyfile
netbox.example.com {
encode gzip zstd
reverse_proxy 127.0.0.1:8080
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
}
}
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://netbox.example.com
Only one gateway should own 80/443. Use correct reachable DNS and test renewal; enable HSTS/includeSubDomains only when the covered hostnames support HTTPS. See Caddy. For CSRF/Host or redirect errors, check ALLOWED_HOSTS, CSRF_TRUSTED_ORIGINS and trusted proxy protocol handling.
Test SMTP with an internal recipient before inviting the team. Configure the sending domain's SPF/DKIM/DMARC through the mail provider; check clocks, DNS, TLS, ports and provider egress rules.
- Network administrators manage the required devices/interfaces/prefixes/VLANs.
- Audit users receive read-only object and change-history access.
- Automation gets a dedicated user/token rather than the administrator's token.
- External systems receive scoped object permissions, expiry where supported and rotation.
Test object restrictions with each role; naming a tenant is not a permission rule. Use HTTPS and a secret store for Ansible, Terraform, CMDB or monitoring integrations. Keep tokens out of command history and CI logs.
The web process, job worker and applicable maintenance scheduler must all work. The original diagnostic includes an older standalone housekeeping service:
docker compose ps
docker compose logs --tail=200 netbox-worker
docker compose logs --tail=200 netbox-housekeeping
First list config --services. The current release template has no netbox-housekeeping service; run that particular log command only on a version that defines it, and follow the selected NetBox version's scheduled-job/maintenance setup. Verify an actual job completes, not just that the worker process exists.
For pending imports or mail, check queue connectivity, worker OOM and database locks. Do not flush queued work. Track memory and disk trends with suitable monitoring.
Save PostgreSQL, media, reports/scripts, plugins, actual env files, .env, Compose files, keys/token peppers and image identities. The original sketch needs a write-stop window and failure handling:
mkdir -p /opt/netbox/backups
docker compose exec -T postgres pg_dump -U "$DB_USER" "$DB_NAME" | gzip > /opt/netbox/backups/netbox-$(date +%F).sql.gz
docker compose cp netbox:/opt/netbox/netbox/media /opt/netbox/backups/media-$(date +%F)
cp .env docker-compose.yml /opt/netbox/backups/
docker compose config > /opt/netbox/backups/compose-$(date +%F).yaml
.env is not automatically exported to your shell. Use explicit known values or the PostgreSQL container's own environment. Run dumps with pipefail, unique filenames, restrictive permissions and gzip/hash checks. Do not accept an empty failed dump. Include all env/configuration files rather than only the reference .env, and use the repository's actual Compose filename. Stop web/worker writes while aligning database and media copies; restart deliberately after confirming success.
Keep encrypted offsite copies and test restoration. Restore into an isolated same-version project, disable external notifications/automation, load database and files, then verify migrations, login, inventory, API, attachments and completed jobs.
- Record the Git commit, digests, plugins and private
docker compose configoutput. - Validate a consistent database/media/configuration backup.
- Rehearse the target release and compatible plugins in isolation.
- Stop writes for maintenance, update deliberately and execute the release's
manage.py migrateprocedure. - Test UI, API, search, permissions, files and jobs before restoring access.
git fetch --tags
git checkout <tested-commit>
docker compose pull
docker compose up -d
docker compose exec netbox /opt/netbox/netbox/manage.py migrate
docker compose exec netbox /opt/netbox/netbox/manage.py check
Do not connect an old application to a migrated database. Rebuild the old version with matching pre-upgrade database/media/configuration and verify it before changing the proxy or DNS.
Inspect docker compose ps, application/database/proxy logs and private 8080. Retain the intended service names postgres and redis or update all matching configuration.
Check ALLOWED_HOSTS, CSRF_TRUSTED_ORIGINS and X-Forwarded-Proto: https from the trusted proxy.
Measure database CPU/RAM/I/O and the queue, reduce import batch size and inspect indexes/plugins. Avoid full index rebuilds during peak traffic.
Inspect WAL, logs, media, images and old backups. Verify the offsite copy before removing files; preserve unique attachments and the only recovery copy.
- Application, PostgreSQL, queues/cache and worker are healthy; required maintenance really executes.
- HTTPS, renewal,
ALLOWED_HOSTSand CSRF origins are tested. - Minimum roles and token rotation work; require MFA through a supported identity provider or verified compatible integration.
- SMTP, password reset and notifications reach a test inbox.
- Database, media,
.env, actual env/configuration and plugin versions are offsite. - A documented isolated restore has succeeded.
- Versions are pinned and API/search/files/jobs are checked after upgrades.
Build a trustworthy model for one site, then expand automation against verified relationships.
Further reading: