Fix up the installation docs

Author: jeremystretch

contrib/gunicorn.conf

@@ -0,0 +1,16 @@
+# The IP address (typically localhost) and port that the Netbox WSGI process should listen on
+bind = '127.0.0.1:8001'
+
+# Number of gunicorn workers to spawn. This should typically be 2n+1, where
+# n is the number of CPU cores present.
+workers = 5
+
+# Number of threads per worker process
+threads = 3
+
+# Timeout (in seconds) for a request to complete
+timeout = 120
+
+# The maximum number of requests a worker can handle before being respawned
+max_requests = 5000
+max_requests_jitter = 500

contrib/gunicorn.py

@@ -1,20 +1,18 @@
 [Unit]
-Description=Netbox RQ Worker
+Description=NetBox Request Queue Worker
 Documentation=https://netbox.readthedocs.io/en/stable/
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=simple
 
-EnvironmentFile=/etc/sysconfig/netbox.env
-
 User=www-data
 Group=www-data
 
-WorkingDirectory=${WorkingDirectory}
+WorkingDirectory=/opt/netbox
 
-ExecStart=/usr/bin/python3 ${WorkingDirectory}/netbox/manage.py rqworker
+ExecStart=/usr/bin/python3 /opt/netbox/netbox/manage.py rqworker
 
 Restart=on-failure
 RestartSec=30

contrib/netbox-rq.service

@@ -1,24 +1,22 @@
 [Unit]
-Description=Netbox WSGI
+Description=NetBox WSGI Service
 Documentation=https://netbox.readthedocs.io/en/stable/
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=simple
 
-EnvironmentFile=/etc/sysconfig/netbox.env
-
 User=www-data
 Group=www-data
-PIDFile=${PidPath}
-WorkingDirectory=${WorkingDirectory}
+PIDFile=/var/tmp/netbox.pid
+WorkingDirectory=/opt/netbox
 
-ExecStart=/usr/local/bin/gunicorn --pid ${PidPath} --pythonpath ${WorkingDirectory}/netbox --config ${ConfigPath} netbox.wsgi
+ExecStart=/usr/local/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
 
 Restart=on-failure
 RestartSec=30
 PrivateTmp=true
 
 [Install]
-WantedBy=multi-user.target
+WantedBy=multi-user.target

contrib/netbox.env

@@ -4,7 +4,7 @@ NetBox requires a PostgreSQL database to store data. This can be hosted locally
     The installation instructions provided here have been tested to work on Ubuntu 18.04 and CentOS 7.5. The particular commands needed to install dependencies on other distributions may vary significantly. Unfortunately, this is outside the control of the NetBox maintainers. Please consult your distribution's documentation for assistance with any errors.
 
 !!! warning
-    NetBox v2.2 and later requires PostgreSQL 9.4 or higher.
+    NetBox requires PostgreSQL 9.4 or higher.
 
 # Installation
 

contrib/netbox.service

@@ -212,15 +212,7 @@ Superuser created successfully.
 ```no-highlight
 # python3 manage.py collectstatic --no-input
 
-You have requested to collect static files at the destination
-location as specified in your settings:
-
-    /opt/netbox/netbox/static
-
-This will overwrite existing files!
-Are you sure you want to do this?
-
-Type 'yes' to continue, or 'no' to cancel: yes
+959 static files copied to '/opt/netbox/netbox/static'.
 ```
 
 # Load Initial Data (Optional)
@@ -254,3 +246,11 @@ Next, connect to the name or IP of the server (as defined in `ALLOWED_HOSTS`) on
 
 !!! warning
     If the test service does not run, or you cannot reach the NetBox home page, something has gone wrong. Do not proceed with the rest of this guide until the installation has been corrected.
+
+Note that the initial UI will be locked down for non-authenticated users.
+
+![NetBox UI as seen by a non-authenticated user](../media/installation/netbox_ui_guest.png)
+
+After logging in as the superuser you created earlier, all areas of the UI will be available.
+
+![NetBox UI as seen by an administrator](../media/installation/netbox_ui_admin.png)

contrib/[email protected]

@@ -107,99 +107,26 @@ Install gunicorn:
 # pip3 install gunicorn
 ```
 
-Save the following configuration in the root NetBox installation path as `gunicorn_config.py` (e.g. `/opt/netbox/gunicorn_config.py` per our example installation). Be sure to verify the location of the gunicorn executable on your server (e.g. `which gunicorn`) and to update the `pythonpath` variable if needed. If using CentOS/RHEL, change the username from `www-data` to `nginx` or `apache`. More info on `max_requests` can be found in the [gunicorn docs](https://docs.gunicorn.org/en/stable/settings.html#max-requests).
+Copy `contrib/gunicorn.conf` to `/opt/netbox/gunicorn.conf`. We make a copy of this file to ensure that any changes to it do not get overwritten by a future upgrade.
 
 ```no-highlight
-command = '/usr/bin/gunicorn'
-pythonpath = '/opt/netbox/netbox'
-bind = '127.0.0.1:8001'
-workers = 3
-user = 'www-data'
-max_requests = 5000
-max_requests_jitter = 500
+# cp contrib/gunicorn.py /opt/netbox/gunicorn.py
 ```
 
-# systemd configuration
-
-Copy or link contrib/netbox.service and contrib/netbox-rq.service to /etc/systemd/system/netbox.service and /etc/systemd/system/netbox-rq.service
-
-```no-highlight
-# cp contrib/netbox.service to /etc/systemd/system/netbox.service
-# cp contrib/netbox-rq.service to /etc/systemd/system/netbox-rq.service
-```
-
-Edit /etc/systemd/system/netbox.service and /etc/systemd/system/netbox-rq.service. Be sure to verify the location of the gunicorn executable on your server (e.g. `which gunicorn`).  If using CentOS/RHEL, change the username from `www-data` to `nginx` or `apache`:
-
-```no-highlight
-/usr/local/bin/gunicorn --pid ${PidPath} --pythonpath ${WorkingDirectory}/netbox --config ${ConfigPath} netbox.wsgi
-```
-
-```no-highlight
-User=www-data
-Group=www-data
-```
-
-Copy contrib/netbox.env to /etc/sysconfig/netbox.env
-
-```no-highlight
-# cp contrib/netbox.env to /etc/sysconfig/netbox.env
-```
-
-Edit /etc/sysconfig/netbox.env and change the settings as required.  Update the `WorkingDirectory` variable if needed.
-
-```no-highlight
-# Name is the Process Name
-#
-Name = 'Netbox'
+You may wish to edit this file to change the bound IP address or port number, or to make performance-related adjustments.
 
-# ConfigPath is the path to the gunicorn config file.
-#
-ConfigPath=/opt/netbox/gunicorn.conf
-
-# WorkingDirectory is the Working Directory for Netbox.
-#
-WorkingDirectory=/opt/netbox/
-
-# PidPath is the path to the pid for the netbox WSGI
-#
-PidPath=/var/run/netbox.pid
-```
+# systemd configuration
 
-Copy contrib/gunicorn.conf to gunicorn.conf
+We'll use systemd to control the daemonization of NetBox services. First, copy `contrib/netbox.service` and `contrib/netbox-rq.service` to the `/etc/systemd/system/` directory:
 
 ```no-highlight
-# cp contrib/gunicorn.conf to gunicorn.conf
+# cp contrib/*.service /etc/systemd/system/
 ```
 
-Edit gunicorn.conf and change the settings as required.
+!!! note
+    These service files assume that gunicorn is installed at `/usr/local/bin/gunicorn`. If the output of `which gunicorn` indicates a different path, you'll need to correct the `ExecStart` path in both files.
 
-```
-# Bind is the ip and port that the Netbox WSGI should bind to
-#
-bind='127.0.0.1:8001'
-
-# Workers is the number of workers that GUnicorn should spawn.
-# Workers should be: cores * 2 + 1.  So if you have 8 cores, it would be 17.
-#
-workers=3
-
-# Threads
-#     The number of threads for handling requests
-#     Threads should be: cores * 2 + 1.  So if you have 4 cores, it would be 9.
-#
-threads=3
-
-# Timeout is the timeout between gunicorn receiving a request and returning a response (or failing with a 500 error)
-#
-timeout=120
-
-# ErrorLog
-#     ErrorLog is the logfile for the ErrorLog
-#
-errorlog='/opt/netbox/netbox.log'
-```
-
-Finally, start the `netbox` and `netbox-rq` services and enable them to initiate at boot time:
+Then, start the `netbox` and `netbox-rq` services and enable them to initiate at boot time:
 
 ```no-highlight
 # systemctl daemon-reload
@@ -209,7 +136,24 @@ Finally, start the `netbox` and `netbox-rq` services and enable them to initiate
 # systemctl enable netbox-rq.service
 ```
 
-At this point, you should be able to connect to the nginx HTTP service at the server name or IP address you provided. If you are unable to connect, check that the nginx service is running and properly configured. If you receive a 502 (bad gateway) error, this indicates that gunicorn is misconfigured or not running.
+You can use the command `systemctl status netbox` to verify that the WSGI service is running:
+
+```
+# systemctl status netbox.service
+● netbox.service - NetBox WSGI Service
+   Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
+   Active: active (running) since Thu 2019-12-12 19:23:40 UTC; 25s ago
+     Docs: https://netbox.readthedocs.io/en/stable/
+ Main PID: 11993 (gunicorn)
+    Tasks: 6 (limit: 2362)
+   CGroup: /system.slice/netbox.service
+           ├─11993 /usr/bin/python3 /usr/local/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/...
+           ├─12015 /usr/bin/python3 /usr/local/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/...
+           ├─12016 /usr/bin/python3 /usr/local/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/...
+...
+```
+
+At this point, you should be able to connect to the HTTP service at the server name or IP address you provided. If you are unable to connect, check that the nginx service is running and properly configured. If you receive a 502 (bad gateway) error, this indicates that gunicorn is misconfigured or not running.
 
 !!! info
-    Please keep in mind that the configurations provided here are bare minimums required to get NetBox up and running. You will almost certainly want to make some changes to better suit your production environment.
+    Please keep in mind that the configurations provided here are bare minimums required to get NetBox up and running. You may want to make adjustments to better suit your production environment.

docs/installation/1-postgresql.md

@@ -20,12 +20,6 @@
     'CONN_MAX_AGE': 300,      # Max database connection age
 }
 
-# This key is used for secure generation of random numbers and strings. It must never be exposed outside of this file.
-# For optimal security, SECRET_KEY should be at least 50 characters in length and contain a mix of letters, numbers, and
-# symbols. NetBox will not run without this defined. For more information, see
-# https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-SECRET_KEY
-SECRET_KEY = ''
-
 # Redis database settings. The Redis database is used for caching and background processing such as webhooks
 # Seperate sections for webhooks and caching allow for connecting to seperate Redis instances/datbases if desired.
 # Full connection details are required in both sections, even if they are the same.
@@ -48,6 +42,12 @@
     }
 }
 
+# This key is used for secure generation of random numbers and strings. It must never be exposed outside of this file.
+# For optimal security, SECRET_KEY should be at least 50 characters in length and contain a mix of letters, numbers, and
+# symbols. NetBox will not run without this defined. For more information, see
+# https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-SECRET_KEY
+SECRET_KEY = ''
+
 
 #########################
 #                       #