From 6f23ab56032d14ca28f2d41bf3307e428e78004f Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 30 Aug 2021 14:15:21 -0400 Subject: [PATCH] Better copy/paste support for installation docs --- docs/installation/1-postgresql.md | 30 ++++++++++++------------ docs/installation/2-redis.md | 5 ++-- docs/installation/3-netbox.md | 39 +++++++++++++++---------------- docs/installation/4-gunicorn.md | 21 ++++++++++------- 4 files changed, 50 insertions(+), 45 deletions(-) diff --git a/docs/installation/1-postgresql.md b/docs/installation/1-postgresql.md index 644b2715c..43b12f0e8 100644 --- a/docs/installation/1-postgresql.md +++ b/docs/installation/1-postgresql.md @@ -40,28 +40,28 @@ sudo systemctl enable postgresql ## Database Creation -At a minimum, we need to create a database for NetBox and assign it a username and password for authentication. This is done with the following commands. +At a minimum, we need to create a database for NetBox and assign it a username and password for authentication. Start by invoking the PostgreSQL shell as the system Postgres user. + +```no-highlight +sudo -u postgres psql +``` + +Within the shell, enter the following commands to create the database and user (role), substituting your own value for the password: + +```postgresql +CREATE DATABASE netbox; +CREATE USER netbox WITH PASSWORD 'J5brHrAXFLQSif0K'; +GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox; +``` !!! danger **Do not use the password from the example.** Choose a strong, random password to ensure secure database authentication for your NetBox installation. -```no-highlight -$ sudo -u postgres psql -psql (12.5 (Ubuntu 12.5-0ubuntu0.20.04.1)) -Type "help" for help. - -postgres=# CREATE DATABASE netbox; -CREATE DATABASE -postgres=# CREATE USER netbox WITH PASSWORD 'J5brHrAXFLQSif0K'; -CREATE ROLE -postgres=# GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox; -GRANT -postgres=# \q -``` +Once complete, enter `\q` to exit the PostgreSQL shell. ## Verify Service Status -You can verify that authentication works issuing the following command and providing the configured password. (Replace `localhost` with your database server if using a remote database.) +You can verify that authentication works by executing the `psql` command and passing the configured username and password. (Replace `localhost` with your database server if using a remote database.) ```no-highlight $ psql --username netbox --password --host localhost netbox diff --git a/docs/installation/2-redis.md b/docs/installation/2-redis.md index e31873d2b..14dda60f1 100644 --- a/docs/installation/2-redis.md +++ b/docs/installation/2-redis.md @@ -28,6 +28,7 @@ You may wish to modify the Redis configuration at `/etc/redis.conf` or `/etc/red Use the `redis-cli` utility to ensure the Redis service is functional: ```no-highlight -$ redis-cli ping -PONG +redis-cli ping ``` + +If successful, you should receive a `PONG` response from the server. diff --git a/docs/installation/3-netbox.md b/docs/installation/3-netbox.md index e0e823aec..43b23a649 100644 --- a/docs/installation/3-netbox.md +++ b/docs/installation/3-netbox.md @@ -36,23 +36,21 @@ This documentation provides two options for installing NetBox: from a downloadab Download the [latest stable release](https://github.com/netbox-community/netbox/releases) from GitHub as a tarball or ZIP archive and extract it to your desired path. In this example, we'll use `/opt/netbox` as the NetBox root. ```no-highlight -$ sudo wget https://github.com/netbox-community/netbox/archive/vX.Y.Z.tar.gz -$ sudo tar -xzf vX.Y.Z.tar.gz -C /opt -$ sudo ln -s /opt/netbox-X.Y.Z/ /opt/netbox -$ ls -l /opt | grep netbox -lrwxrwxrwx 1 root root 13 Jul 20 13:44 netbox -> netbox-2.9.0/ -drwxr-xr-x 2 root root 4096 Jul 20 13:44 netbox-2.9.0 +sudo wget https://github.com/netbox-community/netbox/archive/vX.Y.Z.tar.gz +sudo tar -xzf vX.Y.Z.tar.gz -C /opt +sudo ln -s /opt/netbox-X.Y.Z/ /opt/netbox ``` !!! note - It is recommended to install NetBox in a directory named for its version number. For example, NetBox v2.9.0 would be installed into `/opt/netbox-2.9.0`, and a symlink from `/opt/netbox/` would point to this location. This allows for future releases to be installed in parallel without interrupting the current installation. When changing to the new release, only the symlink needs to be updated. + It is recommended to install NetBox in a directory named for its version number. For example, NetBox v3.0.0 would be installed into `/opt/netbox-3.0.0`, and a symlink from `/opt/netbox/` would point to this location. (You can verify this configuration with the command `ls -l /opt | grep netbox`.) This allows for future releases to be installed in parallel without interrupting the current installation. When changing to the new release, only the symlink needs to be updated. ### Option B: Clone the Git Repository Create the base directory for the NetBox installation. For this guide, we'll use `/opt/netbox`. ```no-highlight -sudo mkdir -p /opt/netbox/ && cd /opt/netbox/ +sudo mkdir -p /opt/netbox/ +cd /opt/netbox/ ``` If `git` is not already installed, install it: @@ -75,7 +73,7 @@ Next, clone the **master** branch of the NetBox GitHub repository into the curre sudo git clone -b master https://github.com/netbox-community/netbox.git . ``` -The screen below should be the result: +The `git clone` command should generate output similar to the following: ``` Cloning into '.'... @@ -250,13 +248,8 @@ Once the virtual environment has been activated, you should notice the string `( Next, we'll create a superuser account using the `createsuperuser` Django management command (via `manage.py`). Specifying an email address for the user is not required, but be sure to use a very strong password. ```no-highlight -(venv) $ cd /opt/netbox/netbox -(venv) $ python3 manage.py createsuperuser -Username: admin -Email address: admin@example.com -Password: -Password (again): -Superuser created successfully. +cd /opt/netbox/netbox +python3 manage.py createsuperuser ``` ## Schedule the Housekeeping Task @@ -276,13 +269,19 @@ See the [housekeeping documentation](../administration/housekeeping.md) for furt At this point, we should be able to run NetBox's development server for testing. We can check by starting a development instance: ```no-highlight -(venv) $ python3 manage.py runserver 0.0.0.0:8000 --insecure +python3 manage.py runserver 0.0.0.0:8000 --insecure +``` + +If successful, you should see output similar to the following: + +```no-highlight +Watching for file changes with StatReloader Performing system checks... System check identified no issues (0 silenced). -November 17, 2020 - 16:08:13 -Django version 3.1.3, using settings 'netbox.settings' -Starting development server at http://0.0.0.0:8000/ +August 30, 2021 - 18:02:23 +Django version 3.2.6, using settings 'netbox.settings' +Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C. ``` diff --git a/docs/installation/4-gunicorn.md b/docs/installation/4-gunicorn.md index 8168ce98b..7b56754fe 100644 --- a/docs/installation/4-gunicorn.md +++ b/docs/installation/4-gunicorn.md @@ -31,18 +31,23 @@ sudo systemctl enable netbox netbox-rq You can use the command `systemctl status netbox` to verify that the WSGI service is running: ```no-highlight -# systemctl status netbox.service +systemctl status netbox.service +``` + +You should see output similar to the following: + +```no-highlight ● netbox.service - NetBox WSGI Service Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled) - Active: active (running) since Tue 2020-11-17 16:18:23 UTC; 3min 35s ago + Active: active (running) since Mon 2021-08-30 04:02:36 UTC; 14h ago Docs: https://netbox.readthedocs.io/en/stable/ - Main PID: 22836 (gunicorn) - Tasks: 6 (limit: 2345) - Memory: 339.3M + Main PID: 1140492 (gunicorn) + Tasks: 19 (limit: 4683) + Memory: 666.2M CGroup: /system.slice/netbox.service - ├─22836 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid> - ├─22854 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid> - ├─22855 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid> + ├─1140492 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va> + ├─1140513 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va> + ├─1140514 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va> ... ```