Installing NetBox v3.0

hi folks my name is jeremy stretch i'm the founder and lead maintainer of the nutbox open source project and in this video we're going to run through installing netbox version 3.0 here you can see the public demo that's been already set up we're basically going to rebuild this on our own private instance first step here is going to be to open the netbox documentation that's found on read the docs or specifically netbox.readthedocs.io and there's a link to that in the project page on github this is all the official documentation for the project including the installation instructions which we can find over here on the left hand side under installation we're going to run through installing a few components to that comprise a full net box deployment namely those are the postgresql database that's the relational database that stores all the actual data inside netbox the redis and memory key value store that's used for things like background task queuing and caching and then we're going to install that box itself so that's everything that kind of goes into um you know the netbox project so that it box code base and related packages and then we're going to install gunnacorn which is the wsgi worker used by the django framework to run the application itself and then finally an http server in front of it specifically nginx in this example so let's go ahead and get started i've got a digitalocean droplet spun up here running ubuntu version 20.04 so this is completely mint we haven't made any changes to this we're just going to follow the instructions verbatim from start to finish all right so the first step here is going to be to install postgresql and the box 3.0 does require postgresql 9.6 or later notice do note that nutbox doesn't support any other backend databases such as mysql it does have to be postgresql so the first thing we're going to do here is just run after update now that's the going to ensure that we're working with up-to-date cache of the of the ubuntu package repository as i mentioned this was a brand new droplet that was just uh but just been deployed so we want to make sure that everything is up to date and looks good there then we're going to go ahead and actually install postgresql [Music] all right that should finish up here in a second now once it's installed we do want to make sure that postgresql is going to be re-initiated upon reboot of the server so to do that we're going to use system control to both enable and ensure that the service is started so we just copy that you'll notice as you go through the documentation that for each of these blocks here with the monospace text there's a little icon on the top right that's going to allow you to just automatically copy the content of that block to your system clip or just for convenience all right so postgresql is installed we'll go ahead and paste those commands in to ensure that the service is enabled then we'll move on with creating the database so to do this we're going to use the psql utility to actually enter the the postgresql command line and we're going to invoke that notice using sudo here as the postgres system user now that we're in there we're going to issue three commands the first one creates the database the second creates a user or role in postgresql vernacular with a password and then the the final command is going to assign privileges for that user to that database uh because this is a demonstration video we'll go ahead and use the same password here from the documentation but of course in real in real life don't use that create your own password and place those commands in there so we see we've got our database created our rules created and then we've granted privileges as expected all right that's actually all we have to do to start with the database so we can go ahead and close out of that terminal and then what we can do down here is just to verify that we that everything is set up correctly we can try connecting to the psql client library and authenticating with the password we used in the documentation just to make sure everything is working as expected so let's try that now first we'll go ahead and close out of that with ctrl d or backslash q and then we're going to invoke the psql client utility with the username netbox and a password to be provided on the command line for uh the database netbox on localhost let's do that let's go grab our password because i don't have to remember what it was paste that in all right and then we see that we're in here notice that we happen to have uh postgresql.8 installed perfectly fine um like i mentioned earlier this has to be 9.6 or later cool so we can go ahead and close out of that so we know postgresql is completed all right our next step is to install redis this is a pretty minimal installation basically we just have to install redis 4.0 or later so we can copy this and just install red a server and then once that's done there's an optional step just to verify that it is running you can use the redis cli utility and issue a ping command which as you might expect will return a pong there you go all right so postgresql and redis are already done let's move on to the meat of the installation which is the box itself so netbox 3.0 and later do require python 3.7 or later so if you're running an older version of ubuntu or you know whatever the underlying operating system is that doesn't uh doesn't provide python at least python 3.7 you'll need to install that you can find guides to install that in parallel with it with whatever the system version of python is for your operating system uh because we're running ubuntu 2004 we've already got python38 i believe it is installed and if you want to check you can just run python3 with the uppercase v there you go python385 is what we'll be using uh so the first step here is to install uh make sure python is installed along with all the dependent packages that we need for netbox so we can just copy and paste that command into the terminal this might take a little bit because it's going to install a number of packages the next step once that's completed and we'll check on that in a second is to ensure that we're working with the latest version of pip and that's pretty much just upgrading pip using pip itself it should wrap up here in just a second feel free to skip ahead in the video if you want to get to the next step all right here we go now like i said we're going to upgrade pip now because by default you typically get a fairly out of date version of pip installed um here we've upgraded to the pip 21.2.4 okay now that we've got our environment set up and ready to go we're going to download nutbox now there's two options for doing this one is that you can download a tarball or a zip file from github and then expand it manually that's certainly an option my preference though is always to just use git to clone the git repository um it's a little bit more convenient for long term so that if you want to update it's a simple matter of just checking out the newer tag or branch it's also the ideal implementation if you plan to do any development locally within that box so we're going to skip down here to option b which is cloning the git repository we just need to make a directory here under opt netbox um but you also need to install git i'm pretty sure yes gets already installed on this so we can skip that stuff that step rather and then we're going to run git clone there's a couple things to notice here first we are going to pull down the master branch that is the latest stable release at any given time of netbox other branches to be aware of are develop under which active development takes place on the current patch release the next upcoming release so for example the current release is 3.0.2 uh everything under 3.3 will show up in the feat and the excuse me the develop branch there's also a feature branch under which we will have any work for 3.1 so the next major release coming up let's go ahead and copy that command you'll also notice that we're limiting it to a depth of one meaning we're only going to get the most recent commit we're going to omit all the you know the year's worth of git history there if you're going to be doing development though you'd probably want to admit that this is called doing a shallow clone you want to do a full clone if you're going to be doing any development work pull that down and now you'll see in our directory we have the netbox installation base so here's everything from the git repository which is over here on github so basically we just pull down all of the files that listed on github are now copied locally using git all right uh next step is to create the system user so we need to define a netbox user under which the netbox processes will run pretty simple we're just going to call it netbox and give it its own little group uh so we've done add user and then uh changing ownership of the opt netbox directory here to ensure that the netbox processes that are running have the ability to write uploaded files to the media directory all right now we move on to netbox configurations now we're going to be modifying the config the python configuration file for netbox itself all right so this is going to be i'm going to start typing the commands here to make sure it's a little more obvious so we're going to go into the netbox in the box directory then you'll see a file here called configuration.example.pi so we're going to copy this this is just an example configuration it's the default uh we're going to copy configuration example.pi to just configuration.i and then we're going to edit this file now there's a few things that we need to do that we need to set in this file first off there's just a handful of required settings and then the rest of it are all optional settings uh so the first one is allowed hosts this is going to tell us the domain names and or ip addresses on which that box should be listening uh in our case we don't have a domain set up for this actually just because it's a demonstration instance so i'm just going to use the ip address here on which we want to listen this is the current public ip of my instance the second configuration parameter here is database so this is going to be every all the configuration parameters for our postgresql database namely the username password the database name and so on now we're just running a local local postgresql service here so we're going to keep host at the localhost but we do need to provide the username which is netbox and the password which was actually part of our earlier setup so you can go back here and just grab this real quick again you shouldn't be doing this um but we're just going to grab this from the documentation real quick all right let me put our password in there the name setting up here is the name of the database itself which happens to also be netbox just by default because that's the name of the database that we created in the first step the third configuration setting down here is redis because we're using local redis with default parameters we actually can just stick with what we have here we don't have to configure a password or database ids or anything like that we're just going to go the defaults if you are have if you happen to be using you know a separate redis service or an external redis server you'll need to adjust those the last one down here is called secret key so this is basically just a random string that jingle will use for things like cookie signing and all that we need to go create one of those and we actually have or rather netbox ships with a convenience python script here that will generate a random string for you so you can run that a few times you see it so it's just going to generate a random thing uh random secret rather so we just copy and paste that we'll go back into our configuration file and we'll set a secret key right there alright so those are our four mandatory configuration settings we have a loud host database redis and secret key you'll notice that down here there are quite a number of additional optional settings and those are all described in the documentation but for just getting up and running this should be sufficient for now all right and here's the in the documentation where it describes everything i just talked about there are some optional requirements as well if you intend to use the nate palm automation library to interact with live network devices you can install that now i'm going to skip that because it does take a little bit of time and i'm going to keep the length of the video from getting too long remote file storage as well we're just going to use local storage for uploaded files so like image attachments and so forth however if you're using a storage service like amazon s3 you'll want to install this so that you can utilize that service okay with all that in place we now have our environments set up we have our dependencies installed and we have our configuration in place now we just need to run the upgrade script so this is the upgrade script that's typically used to upgrade an existing installation it works fine for creating a new installation as well this will handle tasks for us including uh building the python virtual environment so instead of running with all of our system python packages we're going to create a virtual environment with our own python executable that will install everything that we need within it without having without risking interference with other system packages we're also going to run database schema migrations that's you know we have our database created but there's nothing in it yet it doesn't have any tables or anything so it'll take care of running of creating all of those it also build the documentation for local use and aggregating static assets such as css and javascript and all that stuff that netbox needs to run so let's go ahead and run that script now so i'm gonna i'm just gonna cd back into the root directory here and sudo upgrade.shell all right so like i said first it's going to start off by creating a new python virtual environment then it's going to pull down it's going to read this requirements.txt file that pulls down all of our python dependencies so if we look in the repository here we see requirements.text so basically it's just pip is reading this and installing all of these that we need this can take a couple minutes but shouldn't take too long it also checks for any local dependencies so if we had installed napalm or django storages those would be defined in localrequirements.txt all right now we're moving on to the database migration so this is going through and running all of our sql migrations to set up our database it's creating our tables for all the different models in that box and so forth this usually takes about 20 or 30 seconds all right doing some housekeeping there all right now we've moved on to building the documentation so this is going to make sure that the documentation that we see here on read the docs is going to be accessible locally so you can go if you're installing that box in an air gap deployment or something without internet access you'll have access to the documentation locally instead of having to go through a different computer to reach read the docs all right we copied over some static files and now you see we're done uh you do notice this warning here at the bottom it says no existing virtual environment was detected that's expected because this is a brand new installation so it went ahead and created a new one for us and the other notes here are about the next steps in the installation so this is only of no if if we were upgrading an existing installation okay now that we've got everything uh handled through the upgrade script we can wrap up this phase of the installation by creating a super user so this is going to be a basically the admin user for netbox the first user is going to have all permissions first we need to activate the virtual environment so we saw that the script created that for us we do that by sourcing the bin activate file or binary within our virtual environment directory you'll notice that the the prompt has changed here now it starts with the vm in parentheses that's just letting us know that we are active and when we invoke python it's going to be pointing to our virtual environment python rather than the system python which happens to be the same version actually for us because it's just going to be i'm sorry we are actually using 38.10 whereas the system was 385 i believe okay then we are going to run the django's manage.pi command here to use django management commands and that's going to be create super user so let's do that now so i need to be in the net box directory and then i'm going to type python managed up high create super user and it's going to prompt me for a username and password to use i'm going to use admin as the username let's get the email address i'm going to use admin as the password again just to keep things simple okay now we should have our super user created next we have the housekeeping task so this is something that needs to run uh daily uh as part of the nutbox installation basically just to do some well housekeeping uh so that'll do things like uh invalidate uh expired sessions and so forth just kind of keeps things tidy so to do that we're just going to copy this netbox housekeeping shell script that ships with netbox into our daily cron file or folder rather and that will take care of that if you're interested in seeing what that does it looks like this yeah all right it's just running the the housekeeping management command that uh that box provides and there's further documentation on that if you're interested all right at this point we should be good to to run nutbox uh the we don't have the http frontend setup that's like nginx or apache we don't have that in place just yet but netbox itself as far as the application should be able to run so what we're going to do is start the development server here this run server command that's provided by django and basically that's just going to ro to start a development instance of this with kind of a super lightweight http wrapper around it and you'll notice that it is not secure hence the insecure flag there letting us know that what you're doing is not secure but it's fine for testing so we're going to run that hopefully this should just kick off yep there we go so now we are running on django three two seven it's accessible at uh well it's gonna be at rip address we didn't tell it what ip address specifically to look to listen on um so let's try accessing that through a web browser so first let me grab the ip address on which we're listening and you notice that it is calling 8000 here it's running on a non-default port and there we go so here is our our new installation we're running that box 3.02 down here at the bottom you'll notice that i don't have access to anything yet because i'm not logged in so everything is actually blocked out because i have by default login required is going to be true and that's a configuration parameter so let's go ahead and log in we'll log in as our super user again the username was admin and the password was admin there we go now we're logged in we see that obviously nothing's there because we haven't created anything in that box yet but if we wanted to we could go ahead and start creating objects and everything so we see that that works again we're not complete we're not done with the installation yet this is just a development version of the server or for you know for development and testing purposes it's not suitable for production use so before we go any further we'll go back to our console and we'll close that with ctrl c that drops us back to our shell and then we'll move on with the rest of the installation it is important to know as you're installing that box if you get to this point and you're not able to get this this ui working you're not able to access it for whatever reason stop here go back and figure out what's wrong uh don't try to don't don't you know save it for later and assume that you'll be able to fix it later because if you can't get to this point something's gone wrong and you need to figure out what that is before you go any further all right let's move on with gunacorn so this is going to be the application that actually enables the wsgi processes to run a pretty simple setup netbox ships with a default configuration which is available at contrib gunnacorn.pi so we're just going to copy that into optnetbox there uh now if you wanted to let me open that real quick now if you wanted to make changes to this you're certainly more than welcome to these defaults that we provide are going to be suitable for most installations however if you're you know anticipating heavy loads or or extensive multi-processing work you can go ahead and change the number of workers and threads per worker and here and all that and that's all documented by gunnacorn if you want to dig more into that so we've got that set up now we just need to copy our system service file over so that's just copying the file that's provided by netbox and then reloading the daemon let me just copy this and we can take a look at that so again this is coming from the contrib folder we're copying two service files over so it's netbox.service and netbox rq.service these are the uh this the system control uh daemons basically that are going to run that box itself and then we just need to now that we've copied those over we just need to reload the system control daemon all right that should be good now we can check using the system control status command to verify that each service is in fact running as expected oh did i skip a step oh i did geez uh it helps if you start the service first let's do that we'll so we'll start and enable it getting ahead of myself here all right now we've got the sim links created now if we run that status command again there we go in that box that or in the box.service we see that it is active and running and we see the different worker processes in here that we expect so everything is good there we'll also check the status of the net box rq service that is the background process uh worker that's basically just sitting and listening to the redis queue for for background tasks as they come in to handle them separately from the request response web process there we go we just has the one thread running there uh our keyworker is the name of that command so that's good to go as well all right we're in great shape uh if you do run into any problems here if you don't see that both of those services are running the command to run for to get a little more information is journal control with the eu flags set and that's going to give you um basically just more information about what what happens when that service tries to start and why it might not be starting so you'll see output kind of like that and ideally it'll show you any any relevant error messages okay four steps now one step to go the last uh step in the process here is to install an http server um before you before you proceed with this it's recommended to get a uh you know a trusted ssl cert from a reputable provider let's encrypt works great for just free certificates or you might have something available through your you know through your company or if you want to purchase one directly that's that's a possibility as well installations for let's encrypt do vary a little bit depending on your exact setup so i'd recommend i'll point you there for documentation for our purposes we're just going to create a self-signed local certificate uh obviously not idea not suitable for production use but because this is just a demo instance and because i don't want to go through the whole process of assigning a domain and everything and to generate assert we'll just keep the video short by doing it this way so we'll just generate one locally using openssl and copy the command there and just kind of feed it some you know garbage values here all right so now we should have our certificate and key set uh you'll see two options in the installation documentation you can install either nginx or apache i tend to prefer nginx but that's you know completely unwarranted bias they both work perfectly fine you're free to install whichever you you feel more comfortable with or you know any other http daemon as long as it supports wsgi should be perfectly suitable all right so next i'm going to start with installing nginx and we'll let that run once that's installed then we're going to copy the default nginx configuration file provided by netbox again it's in that contrib file at the same place we found the gun accord config and the system control configuration files the service files rather so i'm going to copy that over into the nginx sites available directory okay uh and then i'm going to delete the default nginx configuration you may or may not want to do that depending on your exact setup but typically if if nutbox is the only thing you're going to be running on this at least the only web application then you you're fine to do that if you have a more involved setup you'll probably want to stop and think about the best way to approach that and then because we changed the configuration we're just going to restart nginx real quick okay oh you know i did skip one step in here i need to set the domain of uh well we don't have a domain but we need to give something for the server name here for nginx yeah so we can uh we don't really have a server name i'm just gonna use the ip address again ideally in production you know you'd be using a domain name for this so i'm just gonna use that and then because i modified the configuration i'm going to restart nginx again we can skip the section here on apache and then we just want to confirm connectivity so we'll open a new tab here and we should be able to connect to our ip again i'm going to the security risk warning because i'm using a self-signed tls certificate um i i understand why that's happening if you're using a real certificate again you shouldn't be seeing that should just go like any normal site and here we go we see our ui just like when we're running the django development server uh here it is in all its glory we see the ui um i'm already logged in incidentally because i'm connecting on the same ip address as before so that cookie's still good i can go through and i can you know create sites and everything and from this point netbox is uh fully functional so we've reached the end of the installation again if you run into any problems there's some tips here at the at the end uh if you still are struggling with it you know just go back check me make sure you that you've you're hitting all the all the points in the documentation you're getting all the commands you'll see i've done this a thousand times you'll notice that even i skipped a command right so it happens to the best of us for sure um if you're still struggling with it i'd invite you to go to the netbox github repository here go to the discussions tab and then um just have you know start a new discussion here say hey guys you know i'm uh trying to install in that box running into some issues share as much detail as you can and uh folks will be happy to help you out uh yeah or if you want to try uh just joining our uh netdev community slack you just go to netdev.chat up here click the big blue join button uh that's where netbox uh community chat is hosted uh so you can jump into slack and uh i or someone else so we'll hopefully see it and help you out pretty quick so again lots of different avenues for assistance but hopefully you won't even need to do that um again if you stick with the documentation it should all work out pretty well but if you do have any questions you know let us know and we'll be happy to help uh so that said that is nutbox and uh thank you for watching good luck

Channel: NS1 Labs

Views: 5,639

Keywords:

Id: 7Fpd2-q9_28

Length: 30min 59sec (1859 seconds)

Published: Thu Sep 09 2021