The blue info boxes flag **What You've Missed**, which are stages you should consider in a production, or in "more than just a NetBox lab" environment.
### 5 Minute Demo ### Installation Guide #### 1. Install Ubuntu Server You're going to need to get a server with **Ubuntu 24.04 LTS** up and running. [Download an image](https://ubuntu.com/download/server) like `ubuntu-24.04-live-server-amd64.iso` or spin up an instance on your favorite cloud provider, like AWS. #### 2. Install Semaphore and the Netos NetOps Project You can follow the full [Install Semaphore Guide](https://docs.netos.io/books/semaphore-netops/page/deploy-semaphore-netos-projects), however, in summary, once you install Ubuntu, paste this command to pull the repo and run the install script, and you shouldn't need to do anything else: `sudo wget https://raw.githubusercontent.com/netos-networks/netos-netops/refs/heads/main/easy-deploy.sh && sudo chmod +x easy-deploy.sh && sudo ./easy-deploy.sh` [](https://docs.netos.io/uploads/images/gallery/2024-09/wjPnxkbt4Z0ogrTF-image.png)The [Key Semaphore Principles](https://docs.netos.io/books/semaphore-netops/page/key-semaphore-principles) guide explains more about Semaphore.
Check the [Users, Accounts, and Tokens](https://docs.netos.io/books/semaphore-netops/page/users-accounts-tokens) guide for more information about credentials and variables.
#### 3. Configure Semaphore These steps are optional, so you can skip this for now.Change the `DOMAIN` and `SEMAPHORE_HOSTNAME` variables in the **NetBox Global Settings** Semaphore environment. Follow the [Deploying NGINX & Certificates](https://docs.netos.io/books/semaphore-netops/page/deploying-nginx-certificates) guide.
Deploy self-signed certificates, so you don't get "your connection isn't private" browser warnings. Follow the [Deploying NGINX & Certificates](https://docs.netos.io/books/semaphore-netops/page/deploying-nginx-certificates) guide.
Enable [Semaphore Backups](https://docs.netos.io/books/semaphore-netops/page/semaphore-backup-guide).
#### 4. Deploy NGINX and Self-Signed Cert for NetBox You need to deploy NGINX to connect to NetBox. To fast track, you can just create a self-signed certificate. The default hostname will be `netbox.netos.dev`. [](https://docs.netos.io/uploads/images/gallery/2024-09/UZ5mahAPnD3cl951-image.png)Change the `DOMAIN` and `NETBOX_HOSTNAME` variables in the **NetBox Global Settings** Semaphore environment. Follow the [Deploying NGINX & Certificates](https://docs.netos.io/books/semaphore-netops/page/deploying-nginx-certificates) guide.
Deploy self-signed certificates, so you don't get "Your connection isn't private" browser warnings. Follow the [Deploying NGINX & Certificates](https://docs.netos.io/books/semaphore-netops/page/deploying-nginx-certificates) guide.
#### 5. Install NetBox Browse to the **NETBOX DEPLOY** view in Semaphore to start the installation. The full [NetBox Installation Guide](https://docs.netos.io/books/semaphore-netbox/page/install-netbox) is here. [](https://docs.netos.io/uploads/images/gallery/2024-09/gkzWMYios59nJyix-image.png) If you want to install a specific version, set it here, matching the numeric version from [Releases · netbox-community/netbox (github.com)](https://github.com/netbox-community/netbox/releases). Don't add the `v`, i.e. `v4.1.2` would be `4.1.2`. [](https://docs.netos.io/uploads/images/gallery/2024-09/fIACUdKPF7wErapl-image.png)Configure scheduled daily [NetBox ](https://docs.netos.io/books/semaphore-netbox/page/netbox-backup-guide)Backups or set your own custom frequency.
[Upgrade NetBox](https://docs.netos.io/books/semaphore-netbox/page/upgrade-netbox). For example, maybe you've used the [Restore](https://docs.netos.io/books/semaphore-netbox/page/netbox-restoration-guide) process to restore to an older version and want to upgrade to a newer version.
Enable the [NetBox Maintenance Playbook](https://docs.netos.io/books/semaphore-netbox/page/netbox-health-checks-maintenance) on a daily schedule as per the developer's guidance.
#### 6. Connect to NetBox Once the playbook is complete, you should be able to connect using HTTPS and the IP address to NetBox. Check the [Users, Accounts, and Tokens](https://docs.netos.io/books/semaphore-netops/page/users-accounts-tokens) guide for full details on account and passwords. The default credentials are as follows: - **Username**: `admin` - **Password**: `ohp8toef7Jee` [](https://docs.netos.io/uploads/images/gallery/2024-09/K1H1uubECrlQwMCS-image.png)If you experience any problems, you can run the [Health Check Playbook](https://docs.netos.io/books/semaphore-netbox/page/netbox-health-checks-maintenance) to quickly diagnose common issues. For example, check the logs to catch the reason why NetBox failed to start.
#### 7. Install NetBox Plugins You can [Install and Upgrade](https://docs.netos.io/books/semaphore-netbox/page/deploy-netbox-community-plugins) popular NetBox plugins from within Semaphore, and also [Disable NetBox Plugins](https://docs.netos.io/books/semaphore-netbox/page/disable-netbox-community-plugins). This feature is a work-in-progress, and probably will be for a while...! [](https://docs.netos.io/uploads/images/gallery/2024-09/cZ0FC3AH3LYr2m9U-image.png)If things go wrong in your test environment, you can quickly [Wipe NetBox](https://docs.netos.io/books/semaphore-netbox/page/remove-netbox) and start again.
# Install NetBox ### Introduction This guide details how to deploy a new instance of NetBox. For guidance on upgrading NetBox, please refer to this [Upgrade NetBox](https://docs.netos.io/books/semaphore-netbox/page/upgrade-netbox).NetBox is installed from the [public GitHub repository](https://github.com/netbox-community/netbox) according to the version set in Semaphore (or proposed during an upgrade). Netos **has not forked** NetBox. Any customizations made by Netos are optional and controlled from within the NETOS view in the NetBox project in Semaphore.
### Configuration Guide #### 1. Configure the Semaphore Environment You can set the `SUPER_USER` username, email, and password in the **NetBox Global Settings** environment settings, or just use the defaults for testing: [](https://docs.netos.io/uploads/images/gallery/2024-09/sEXwOttqGjSC4bdR-image.png)Please don't change the install directory from `/opt/netbox` as it is hard coded in configuration files and variables.
There is a [bug in Ansible Semaphore](https://github.com/semaphoreui/semaphore/issues/2293) that requires you to delete and recreate the secret value. Save doesn't work.
#### 2. Deploy NGINX and the Cert Refer to the following guide [Deploying NGINX & Certificates](https://docs.netos.io/books/semaphore-netops/page/deploying-nginx-certificates) for a detailed guide on deploying NGINX and certs. Once you've deployed, you'll see a screen like this and should be able to connect to a URL like https://uk-lab-nb05-netbox.core.netos.io. [](https://docs.netos.io/uploads/images/gallery/2024-09/najqx4QkhBTa2lpY-image.png)You need to deploy NGINX because it configures the webserver to mount `alias /opt/netbox/netbox/static/;` correctly to avoid the [Static Media Failure](https://stackoverflow.com/questions/62102664/static-media-failure-with-nginx-and-gunicorn) error.
#### 3. Install NetBox We have included pre-defined NetBox templates (which will be updated from time-to-time), for example, you can just click play on the Semaphore template to deploy NetBox `v3.7.8` or `v4.0.11`. [](https://docs.netos.io/uploads/images/gallery/2024-09/A5BzjtElionPicRv-image.png) If you want to install a custom version of NetBox, you can do so by editing the tags in the Semaphore Template. For example, change `--tags=X.X.X` to `--tags=3.6.5`. This feature is useful for a migration, for example, if you wanted to migrate from a legacy NetBox instance, you could take a backup and [Restore](https://docs.netos.io/books/semaphore-netbox/page/netbox-restoration-guide), then [Upgrade](https://docs.netos.io/books/semaphore-netbox/page/upgrade-netbox). [](https://docs.netos.io/uploads/images/gallery/2024-09/FsLJHLmRh2vXLvXz-image.png) Note that the `netbox-deploy.yml` Ansible playbook has logic that matches the tags referenced in Semaphore. The tags must be set for this playbook to execute. The tags are used to set variables which are passed to the `netbox-deploy` Ansible role. ```yaml - hosts: 127.0.0.1 connection: local become: yes vars_files: - ./vars/env-netbox-settings.yml tasks: - name: Set NetBox release version to v4.1.1 set_fact: NETBOX_RELEASE: 4.1.1 tags: 4.1.0 - name: Set NetBox release version to v4.1.0 set_fact: NETBOX_RELEASE: 4.1.0 tags: 4.1.0 ``` #### 4. Connect to NetBox Once you've deployed NetBox you can connect to the application based on the `NETBOX_HOSTNAME` and `DOMAIN` variables configured in the NetBox Global Setting environment. Check the [Users, Accounts, and Tokens](https://docs.netos.io/books/semaphore-netops/page/users-accounts-tokens) guide for full details on account and passwords. The default credentials are as follows: - **Username**: `admin` - **Password**: `ohp8toef7Jee` ##### a. NetBox 3.7.8 [](https://docs.netos.io/uploads/images/gallery/2024-09/lwiS3RbQZsEhpi87-image.png) ##### b. NetBox 4.0.11 [](https://docs.netos.io/uploads/images/gallery/2024-10/7MVITL9DIZzOn5Al-image.png) ### Thoughts About DockerWe (Netos) used and tested the [NetBox Docker](https://github.com/netbox-community/netbox-docker) image for over 6 months. When we started to load test to simulate a large production enterprise environment, we experienced stability issues, especially when hitting the API hard, and also had to make a number of changes to the Docker NGINX configuration.
Others may have had success; however, we were unable to achieve stability (outside of development environments) with NetBox in Docker. The playbooks here install NetBox natively on the Linux operating system, and we've had no issues whatsoever.
# Upgrade NetBox ### Introduction This guide will walk you through the process of upgrading NetBox, including a suggested pre-staging strategy. The approach we take to upgrading NetBox is as follows: 1. Upgrade to the final patch of the current release, e.g. from `3.7.4` to `3.7.8` 2. Upgrade to the final patch version of the next major release, e.g. from `3.7.8` to `4.0.11`The official NetBox upgrade strategy can be found here: [netbox/docs/installation/upgrading.md at develop · netbox-community/netbox (github.com)](https://github.com/netbox-community/netbox/blob/develop/docs/installation/upgrading.md)
This feature is a work-in-progress. There are many other considerations to take into account, such as plugin configurations and customizations, as well as sequencing.
### Upgrade Playbooks and Templates Within the NetBox Deploy view in Semaphore, you'll see these playbooks. - **NetBox Upgrade Check Path** - checks the current running version with the mapping table to suggest the next version. - **NetBox Upgrade to Next Suitable Version** - this will take the result from the "Check Path" playbook and perform an upgrade. [](https://docs.netos.io/uploads/images/gallery/2024-09/DppUnx16QZeKRlCS-image.png) #### Checking the Upgrade Path The following screenshot shows that NetBox `3.7.8` has been detected, and based on the upgrade path mapping table, the next suggested version is `4.0.11`. [](https://docs.netos.io/uploads/images/gallery/2024-09/r7POsdI4tVftAd9f-image.png) When the playbook runs it checks a mapping table that is structured like this. The logic is: 1. If `current_version` and `patch` are the different, then upgrade to the next `patch` in the same release 2. If `current_version` and `patch` are the same, then upgrade to `next_major` ```yaml netbox_upgrade_paths: 3.7.0: patch: 3.7.8 next_major: 4.0.11 3.7.1: patch: 3.7.8 next_major: 4.0.11 3.7.2: patch: 3.7.8 next_major: 4.0.11 3.7.3: patch: 3.7.8 next_major: 4.0.11 3.7.4: patch: 3.7.8 next_major: 4.0.11 3.7.5: patch: 3.7.8 next_major: 4.0.11 3.7.6: patch: 3.7.8 next_major: 4.0.11 3.7.7: patch: 3.7.8 next_major: 4.0.11 3.7.8: patch: 3.7.8 next_major: 4.0.11 4.0.0: patch: 4.0.11 next_major: 4.1.0 ```In a production environment you should not upgrade past the final release in the last release. For example, once `4.0.0` was released, `3.7.8` was considered the final stable release. Once `4.1.0` was released, we would consider `4.0.11` stable, and so on.
#### Running the Upgrade Here you can see that the suggested upgrade version from the mapping table has been passed to the `netbox-deploy` playbook to facilitate the upgrade. [](https://docs.netos.io/uploads/images/gallery/2024-09/X9FOmLW5G2XvevSC-image.png)You must take a [full backup](https://docs.netos.io/books/semaphore-netbox/page/netbox-backup-guide) before starting the upgrade. If possible, we would suggest stopping all services on the server and taking a snapshot (disk image) before proceeding.
Ensure you check compatibility with any plugins that you have installed and have a [clear upgrade path for them](https://docs.netos.io/books/semaphore-netbox/page/deploy-netbox-community-plugins).
Ensure you check breaking changes in the [NetBox Release notes](https://github.com/netbox-community/netbox/releases) that could impact you, for example, if you have integrated your systems using the [NetBox Rest API](https://netbox.readthedocs.io/en/stable/integrations/rest-api/), endpoints do change from time-to-time, which could break your integrations.
Have a clear test plan.
### Pre-Stage Your Upgrades It's fast and simple to spin up a staging NetBox instance for testing. A "belt and braces" approach to an upgrade is as follows: 1. [Install Semaphore](https://docs.netos.io/books/semaphore-netops/page/deploy-semaphore-netos-projects) 2. [Install NetBox, ensuring that you match the NetBox version](https://docs.netos.io/books/semaphore-netbox/page/install-netbox) 3. [Backup your current production NetBox instance](https://docs.netos.io/books/semaphore-netbox/page/netbox-backup-guide) 4. [Restore to the new staging NetBox instance](https://docs.netos.io/books/semaphore-netbox/page/netbox-restoration-guide) 5. Test the upgrade process in safety! # Remove NetBox ### Introduction In a test or lab environment it is useful to be able to quickly wipe NetBox so you can [re-install](https://docs.netos.io/books/semaphore-netbox/page/install-netbox) and [restore](https://docs.netos.io/books/semaphore-netbox/page/netbox-restoration-guide). [](https://docs.netos.io/uploads/images/gallery/2024-09/CExlcQOhNpdbi7Nl-image.png)This process will drop the NetBox database from PostgreSQL and delete the `/opt/netbox` folder. It's probably not a good idea to run this on production system. In fact, delete the template on production systems!
# NetBox CSRF Settings ### Introduction This playbook `netbox-csrf` will add your domains in the following format to the NetBox `settings.py` file based on the `DOMAIN` variable in Semaphore. - `http://*.yourdomain.com` - `https://*.yourdomain.com` - `http://yourdomain.com` - `https://yourdomain.com` When you run the playbook, it will look like this: [](https://docs.netos.io/uploads/images/gallery/2024-09/FIFPzvJXKrPhjm3J-image.png) ### Use Case If your server name is `uk-lab-nb01.core.netos.io`, and you configured a DNS CNAME to give it a more friendly name like `demo2.netos.io` via a reverse proxy, then you would see this error and won't be able to login: [](https://docs.netos.io/uploads/images/gallery/2024-09/Gek6Giygy04COwqM-image.png) To fix this, change the domain to in the NetBox Global Settings: [](https://docs.netos.io/uploads/images/gallery/2024-09/ExXDkAV0PMPqSzYi-image.png) Which will create a `settings.py` file entry like this and fix the error: `CSRF_TRUSTED_ORIGINS = getattr(configuration, 'CSRF_TRUSTED_ORIGINS', ['http://netos.io', 'https://netos.io', 'http://*.netos.io', 'https://*.netos.io'])`