# 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).

<p class="callout warning">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.</p>

### 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:

[![image.png](https://docs.netos.io/uploads/images/gallery/2024-09/scaled-1680-/sEXwOttqGjSC4bdR-image.png)](https://docs.netos.io/uploads/images/gallery/2024-09/sEXwOttqGjSC4bdR-image.png)

<p class="callout warning">Please don't change the install directory from `/opt/netbox` as it is hard coded in configuration files and variables.</p>

<p class="callout danger">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.</p>

#### 2. Deploy NGINX and the Cert

Refer to the following guide [Deploying NGINX &amp; 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 <span style="text-decoration: underline;">https://uk-lab-nb05-netbox.core.netos.io</span>.

[![image.png](https://docs.netos.io/uploads/images/gallery/2024-09/scaled-1680-/najqx4QkhBTa2lpY-image.png)](https://docs.netos.io/uploads/images/gallery/2024-09/najqx4QkhBTa2lpY-image.png)

<p class="callout warning">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.</p>

#### 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`.

[![image.png](https://docs.netos.io/uploads/images/gallery/2024-09/scaled-1680-/A5BzjtElionPicRv-image.png)](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).

[![image.png](https://docs.netos.io/uploads/images/gallery/2024-09/scaled-1680-/FsLJHLmRh2vXLvXz-image.png)](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

[![image.png](https://docs.netos.io/uploads/images/gallery/2024-09/scaled-1680-/lwiS3RbQZsEhpi87-image.png)](https://docs.netos.io/uploads/images/gallery/2024-09/lwiS3RbQZsEhpi87-image.png)

##### b. NetBox 4.0.11

[![image.png](https://docs.netos.io/uploads/images/gallery/2024-10/scaled-1680-/7MVITL9DIZzOn5Al-image.png)](https://docs.netos.io/uploads/images/gallery/2024-10/7MVITL9DIZzOn5Al-image.png)

### Thoughts About Docker

<p class="callout info">We (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.</p>

<p class="callout info">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.</p>