NetBox - Developer Guide

Learn how to deploy NetBox on AWS with our step-by-step guide. It walks you through launching the Meetrix NetBox AMI with CloudFormation, pointing your domain at it, logging in for the first time, adding your first site and prefix, creating an API token for automation, and keeping the server healthy once it runs.

NetBox is the open-source source of truth for network infrastructure. It brings IP address management (IPAM) and data center infrastructure management (DCIM) together, so your sites, racks, devices, cables, prefixes, IP addresses and VLANs live in one database instead of a dozen spreadsheets. Because everything is reachable over an API, NetBox is also where automation reads its inventory from: our article on the benefits of Ansible automation covers the playbook side, and NetBox can serve as its inventory. Running NetBox on your own AWS account keeps that map of your network on infrastructure you control.

Launching the AMI

Step 1: Find and Select NetBox AMI

1. Log in to your AWS Management Console.
2. Navigate to 'NetBox' in AWS Marketplace.

Step 2: Initial Setup & Configuration

1. Click the "Continue to Subscribe" button.
2. After subscribing, accept the terms and click "Accept Terms".
3. Wait a few minutes until processing completes, then click "Continue to Configuration".
4. Select "CloudFormation script to deploy NetBox" as the fulfillment option and choose your region. Click "Continue to Launch".
5. From the "Choose Action" dropdown, select "Launch CloudFormation" and click "Launch".

Create CloudFormation Stack

Step 1: Create a stack

1. Ensure the "Template is ready" option is selected under "Prepare template".
2. Click "Next".

Step 2: Specify stack options

1. Provide a unique "Stack name".
2. Enter the "AdminEmail" used for SSL certificate generation.
3. Enter an "AdminPassword". This is the password for the NetBox admin superuser you log in with, so store it securely.
4. Enter a value for "DeploymentName".
5. Provide a public domain for "DomainName". NetBox will automatically try to set up SSL if the domain is hosted on Route 53. If unsuccessful, you must set up SSL manually.
6. Choose an instance type "InstanceType" (Recommended: t3a.medium).
7. Select your preferred "KeyName".
8. Enter the name of your S3 bucket for "S3Bucket", used for storing backups.
9. Set "SSHLocation" to 0.0.0.0/0, or restrict it to your own IP range.
10. Keep "SubnetCidrBlock" as 10.0.0.0/24.
11. Keep "VpcCidrBlock" as 10.0.0.0/16.
12. Click "Next".

Step 3: Configure stack options

1. Choose "Roll back all stack resources" and "Delete all newly created resources" under "Stack failure options".
2. Click "Next".

Step 4: Review

Review and verify the parameters you've entered.

1. Tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names".
2. Click "Submit".

Afterward, you'll be directed to the CloudFormation stacks page. Please wait 5-10 minutes until the stack status shows CREATE_COMPLETE.

Update DNS

Step 1: Copy IP Address

Copy the public IP labeled "PublicIp" in the "Outputs" tab.

Step 2: Update DNS

1. Go to AWS Route 53 and navigate to "Hosted Zones".
2. Click Create record.
3. Add a record name matching the DomainName you entered, keep the record type as A, and paste the copied PublicIp into the value textbox.
4. Click "Create records".

Access NetBox

Access NetBox using the "DashboardUrl" in the Outputs tab. Until DNS and SSL are in place you can use "DashboardUrlIp" instead, which serves NetBox over plain HTTP.

On the login screen, enter the username admin and the AdminPassword you set in the stack parameters, then click "Sign In".

After logging in you land on the NetBox dashboard. The navigation on the left groups everything NetBox tracks, from Organization, Racks and Devices to IPAM, VPN, Virtualization and Circuits. The widgets show zero objects until you start adding your own.

Add Your First Site and Prefix

Most NetBox objects hang off a site, so start there, then record the address space it uses.

1. Open Organization in the navigation, go to Sites and click "Add".
2. Enter a Name (for example, the data center or office it represents). NetBox fills in the Slug for you. Set the Status, then click "Create".
3. Open IPAM, go to Prefixes and click "Add".
4. Enter the network in CIDR notation, such as 10.10.0.0/16, assign it to the site you just created, and click "Create".

From there you can add racks to the site, then manufacturers, device types and devices, and NetBox will show which addresses in each prefix are used and which are free. The NetBox documentation describes every object in the data model and how they relate.

Create an API Token

Scripts, Ansible playbooks and other tools talk to NetBox through its REST API, and each one needs a token.

1. Click your username in the top-right corner and open API Tokens.
2. Click "Add". Leave write enabled off unless the tool needs to change data, and set an expiry date if the token is temporary.
3. Click "Create" and copy the token right away. NetBox does not show the full token again.

Test the token by asking NetBox for its status, replacing the domain and token with your own:

curl -H "Authorization: Bearer <your API token>" \
  -H "Accept: application/json" \
  https://<your NetBox domain>/api/status/

A JSON response with the NetBox and Python versions means the token works. You can browse the whole API at /api/ on your NetBox domain, and the interactive reference lives at /api/schema/swagger-ui/. The official REST API guide covers filtering, pagination and token formats in detail.

Generate SSL Manually

NetBox will automatically try to set up SSL when a Route 53-hosted domain is provided. If it fails, follow these steps to generate SSL manually.

Step 1: Copy IP Address

1. Follow the Update DNS steps above, if not already done.
2. Copy the Public IP indicated as "PublicIp" in the "Outputs" tab.

Step 2: Log in to the server

1. Open the terminal and go to the directory where your private key is located.
2. Run the following command, replacing the key name and IP address.
3. Type "yes" and press Enter to confirm.

ssh -i <your key name> ubuntu@<Public IP address>

Step 3: Generate SSL

Run the following command and follow the prompts:

sudo /root/certificate_generate_standalone.sh

Once the certificate is in place, switch any scripts or integrations that call the API over http to the https DashboardUrl.

Check Server Logs

Step 1: Log in to the server

ssh -i <your key name> ubuntu@<Public IP address>

Step 2: Check the logs

List the running containers, then view the logs of a container using the first few characters of its container ID. NetBox depends on PostgreSQL and Redis, so check those containers as well if NetBox does not load:

sudo docker ps

sudo docker logs <container-id-prefix>

Shutting Down NetBox

1. In CloudFormation, click the link labeled "Instance" in the "Resources" tab to open the EC2 instance.
2. Stop the NetBox instance from the Instance state dropdown. You can restart it later as needed.

Remove NetBox

Delete the CloudFormation stack from the AWS Management Console under "CloudFormation Stacks" by clicking "Delete".

Upgrades

When a new version is available in AWS Marketplace, remove the previous deployment after backing up necessary server data, and relaunch with the new version.

Troubleshoot

If you face vCPU quota limits, request an increase: How to increase AWS quota.

If you face insufficient capacity errors while creating the stack, try another region or time.

If NetBox shows a 502 Bad Gateway error, wait 5-10 minutes and retry. NetBox runs its database migrations on first start, which can take a few minutes after the instance boots.

If API calls return 403 Forbidden, check that the token has not expired, that it has write access for requests that change data, and that the request sends it in the Authorization header.

Check whether the instance storage is full. Log into the server and run:

df -h

If the root volume is between 90-100%, resize the EBS volume, then reboot and restart the service.

Conclusion

The Meetrix NetBox Deployment Guide helps you run a source of truth for your network in your AWS environment, with the data in a database you control. Whether you're a network engineer, DevOps engineer, or IT lead, this guide provides step-by-step instructions for a secure setup. See the NetBox store page for what the Meetrix image includes. NetBox records what your network should look like; to watch how it actually behaves, our Grafana developer guide sets up monitoring dashboards on AWS, and the Headscale developer guide gives your team private access to the networks NetBox documents. The source code and release notes are on GitHub.

Technical Support

Reach out to Meetrix Support (aws@meetrix.io) for assistance with NetBox issues.