GitLab MR-Buddies, 25 Sep 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Setting up the GitLab Handbook for Local Development

Description

Making handbook changes is sometimes easier to do when you have the immediate feedback of the local development environment. This tutorial shows you how you can get that set up on MacOS.

--------------------------------------
Handbook alias

alias handbook="cd ~/Documents/projects/www-gitlab-com/sites/handbook && code . && open http://localhost:4567 && bundle install && bundle exec middleman"

A

All right hi everyone uh today, I want to go through running the gitlab handbook locally on your macbook and making edits to the page locally having it live reload when you make those changes and just make the whole handbook editing experience a lot nicer for everyone.

A

So basically we can do this by by following some of the tutorials in the handbook documentation in on gitlab to set this up locally. um It is a little bit challenging, which is why I'm making this video. So hopefully this helps you get up and running.

A

First thing: we're going to do is: go to gitlab.

A

Slash get lab dash com, slash.

A

Www.Gitlab.Com, so this is a fresh installation of mac os it's running in a virtual machine, so it's a little bit slower, but basically, if you just got your macbook, you know this is what it's going to look like, even if you haven't really changed that much and you've been using it for a while. It should look pretty similar to this so yeah.

A

First, we go to the the handbook, repo www.gitlab.com, so uh in here we actually have the the main readme and there is a section on local development which we're going to follow so we'll open that up in its own tab. So we have it there available for us.

A

So first step it says, is install homebrew, so we'll open that up. So homebrew is a package manager, as it says here.

A

You don't have to worry too much about what that means, but we just basically copy this line here now. Next thing you want to do is open up the terminal app on mac os. That's this one here!

A

So once you've copied this this line, you can just paste it into your terminal and press enter or return. It's going to ask you for your password, so you just need to type that in don't worry that it doesn't show anything while you're typing. It's still registering your keystrokes.

A

It's just that for security purposes. It doesn't show you uh exactly what you're typing or it doesn't show you even the dots so that people that you know don't know that it's that's the length of your password, so you just have to enter your password in it's going to ask you to press return to continue, so you can just press return and then you'll have to wait for this. To finish,.

A

Okay, so that step is now done. um I did pause the recording there because it takes quite a while. I actually had to cancel mine and restart it because uh it seemed like the internet connection was a bit spotty so, second time around it was. uh It was a lot faster, but yeah. If you have any issues um you know that might take. You know 15 minutes to download. If you, if you've got a slow internet connection, it should be around five minutes or less for most people.

A

I think okay, so we're going to now do step two.

A

So first we're going to actually create a file which is going to make step 2 a little bit easier, so we're just going to in our terminal type the following and touch and then tilde forward, slash, dot, h, r c, okay and the tilde symbol is to the left of your one key in the top left of your keyboard, underneath the escape key. If you can't find it so we'll just do that.

A

Okay, that's going to make this next step a little bit easier. So if we hop over to the nvm website, scroll down to the installing and updating section copy, this command here, okay and then back in your terminal, just paste that and we're going to run it okay.

A

So now you should actually see here that it's appending nvm source string to this dot, zs hrc file- if you don't see that, then probably you didn't create the file correctly you're in the correct location, so you'll just have to go back to the previous step, make sure you've run that command exactly as I've shown it there and then rerun that that curl command this whole thing: okay, and just to make this a little bit easier, I'm just going to do source tilde forward slash.shrc.

A

So let's head back to the local development readme here what it says here is we first have to uh well. We have to run this within the www.gitlab.com directory, so we don't actually have that yet, because we haven't checked out this repo.

A

So if we just hop back to that original page that we went to here, you can go to the clone button. Let's grab the https version of this.

A

If you have your ssh key set up, you can use the ssh version of this, but just for, for a sake of simplicity, I'm just going to use this version in case anybody doesn't have it set up. So.

A

Let's, let's just quickly go and put it in a nice place, so right now we're in the home directory for my user. What we want to do is we want to find a nice location to put this repository on our local system, so I'm going to do cd documents and then, in this directory, I'm going to create a directory called projects. So I'm going to do mkdir which stands for make directory projects.

A

Okay and if I type ls I'll, have to just give it permission. So you can see when I type ls, that it tells me that there's a directory here and that directory is called projects. So I'm going to do cd projects. Cd stands for change directory.

A

Okay! So then, within this directory, I'm going to create this um gitlab handbook project, so um we're going to use the git cli here to do this. um So let me just check that it's installed first yep, so we've got git there, so we can just do git clone and then we can paste the url that we got from from copying it from here.

A

Okay, so if I just press enter there, it's going to go ahead and download all of that direct all of that repository into this new directory that um that we've created called projects. So I'm probably going to stop the video here, because it's quite a large project um and then I'll start up when it's done.

A

Okay, so that step is done now uh that one was pretty long. It's a 4.26 gigabyte repository so um yeah. It took probably around uh 10 minutes or so to download.

A

So now we're going to run the last bit of step 2 here, nvm install on nvmuse, but first we have to make sure that we're in the correct directory so because we downloaded our our handbook project before we just have to make sure that we go to that directory. So I'm going to go cd, tilde documents, projects.

A

Www.Gitlab.Com so now I'm in the correct directory here, okay, so now we can run these commands in step two. So the first one is nvm.

A

Install that might take a few seconds just to download the correct uh dependencies there.

A

Okay, so that's done, and then we just have to do. Nvm use okay and that's it for that step. So, let's clear the terminal there and go on to step three so step three is to install yarn.

A

Let's open that up there.

A

Okay, we can yeah, you just might have to wait a few seconds for it to detect your operating system, so mac os stable whatever the latest version is for you, so we can just use homebrew to do this. That's probably the easiest way. So, let's copy that hop back into our terminal paste.

A

And then we'll just wait for that to download and install shouldn't take too long either.

A

There we go it's done, let's just make sure that it's available so yarn, v, okay, so that gives us the version. If you get an error here, that means that it probably didn't succeed in installing installing properly that's okay, just um make sure you've done all the steps that I've shown here. Just try it again and see if it works a second time.

A

Okay and that's all- we have to do for step three so step four rb, and so let's open up the rbn website here, just have to scroll down uh we'll just click on installation here, so we're using homebrew on mac os okay. So we can just again copy this step. One code here, I'm just going to clear this again paste.

A

And wait for that to install.

A

Okay, so that's done now all right, so let's do step two of the rbm installation just copy this command here go over to your terminal, paste it and press enter, and here it's telling us that you know if we want this to be loaded automatically. We need to add this line here to our zs hrc file.

A

Okay, so one way to do that is just to do echo.

A

Put a single quote and then paste that command put another single quote, and then you can do two arrows, so these ones are just to the right a couple of keys to the right of your m key on your keyboard.

A

You have to hold shift and then you can put in tilde forward slash dot, z, s, h, r c.

A

Okay and if you want to check that that worked just do cat for tilde forward, slash dot, z, s hrc and you can see at the bottom of the file there we have our uh a new command is appended there.

A

Okay, then we probably want to do source tilde forward, slash dot, zs hrc again just to make sure that that's loaded and then we can go to. We can skip step three, because we just did that source command. That's all that that really does. Is it just reloads the configuration okay?

A

Then we can run this command here, just to make sure that our installation is correct. So let's paste that and see what it says.

A

Okay, so it looks like everything is okay, good and then we just need to.

A

Basically, use this script here or this command here, rb amp install to install the ruby versions that we want, but I'm not going to run it on its own, like that, I'm going to go back here and we're going to follow the instructions uh here. So um it says, do not use a system ruby! That's fine! We've already installed um ibm, so we can set up our uh our ruby version as per what the gitlab.com or www dash to get labcom project tells us, so we can basically copy this.

A

We need to make sure that we're in the correct directory, if you're, not in that directory, just do cd tilde forward, slash documents, slash projects, slash www.getlab.com,.

A

Okay should be in the right directory now and then we can run rbn install.

A

All right, so that's done now. I took a little while so I did pause the video again but yeah that should have installed our version as of today version 2.6.5, um but whenever you run it it'll, it should just install the version. That's current for the the handbook.

A

So uh next thing we probably want to run is this here. um Alternatively, you can just close and reopen your your terminal, but we'll run this one just because it's a bit quicker, okay and then we need to do the uh the last little step here. So they're asking us to have a look in the dot ruby version file to see what the version is.

A

I'm pretty sure it's 2.6.5, but let's just have a look, so cat dot, ruby dash version, yup 2.6.5, so we can run rb and local 2.6.5.

B

A

And let's head to step six, let's clear the terminal! First, all right: gem install bundler.

A

Just run that, and that might take a little bit of time to run so I'll pause. The video.

A

A

Okay, that one was a little bit quicker than what I thought it would be, uh but that's all we have to run for step six. Okay, let's do step seven here, so I'm not going to use uh the first command here. I think we're going to use the pi end instead, just because it's going to be a little bit, give us a bit more assurance that we're on the right version of python. So I'm going to start with this brew. Install payment command here, paste that in the terminal run.

B

A

Okay, that's done, then we'll run the next command.

A

Okay, so that's done now: we've got a similar command here to the rbn one that we ran before. I'm gonna. Add this to our zshrc as well. So we do echo single quote: eval.

A

Pi and init dash and then single quote again, so that's basically just drop. What's here in the single quotes and then a couple of arrows tilde forward, slash dot, set shrc.

A

And now we can do source dot, zs, hrc, okay and then we'll run the next command. Here I am global, 3.8.2 I'll, just paste it.

A

Okay, there we go.

A

uh All right, so we're done with the main prerequisite step here that we had to set up uh so now we're in the uh the sort of steps around running the actual handbook, so um we're going to use a a uh a library called middleman, which is uh a ruby library. So we'll just follow these steps here.

A

um It actually tells you here that if you're only using the handbook, then you can just go to the site's handbook directory, uh which I definitely recommend it's a lot quicker, so we'll have to make sure that we're back in our repositories. So let's do cd, tilde documents, projects www.kitlab.com!

A

Okay! Now we can do cd sites, slash handbook, all right now. Your terminal should tell you you're in the handbook directory there. So here we can do bundle, install.

A

This might take a bit of time to run because it's got to download all the dependencies. It'll be a lot quicker, the subsequent times that you run it, but the first time it'll take a bit of time.

A

Okay, so when you see this http message here, that means that it's done so. The next step is to actually run this, but I'm actually going to change this a little bit because we don't ever want the contracts to be checked. So I'm gonna uh get you to change your zs hrc file again uh to add this line. So let's just do echo single quote: export no underscore contracts equals true and single quote and we'll do the double arrow again into tilde forward, slash dot, zs hrc.

B

A

And then I'm also going to get you to do another one which is to enable live reloading. So that's this one here, so we can do the same thing. Echo export I'll, just paste it this time single quote into zs hrc like that and then we'll just source the zshrc file again to load that up okay.

A

Now, basically, all we need to do is run this command here.

A

So this is something you'd run again within the handbook, site's handbook directory, and this will actually run the handbook for local development. So this is our last step. Basically, so we'll just wait for that to load. It takes a little bit of time, probably about two or three minutes before it actually starts the web server. So we'll just wait for that to happen now.

A

Okay, so it is actually listening now for uh requests to our local host, but we're still waiting for the uh the build to complete. So we'll just wait a little bit longer.

A

In the meantime, I'll just load up the website, so here in your browser, you can just type localhost.

A

A

It looks like it has started up now and there you go, we've got the handbook.

A

Okay, so as one little final step to this whole process, um we're going to download visual studio code because you can use the visual studio code to edit the handbook locally. And we.

B

A

Use it to edit some of the configuration files that we're working with, so you want to go to code.visualstudio.com and you want to do download for mac, and once you have that installed, you also want to do one extra step. So if I open up my visual studio code.

B

A

And then, once it's open here, you want to basically do command shift p, which will open up this little thing with the arrow here and then you can just type code and then look for the one that says: shell command, install code command in path. So you want to click on that one, and then it should say that it successfully installed code to your path. So what that will? Basically let us do is in our terminal.

A

We can go to any directory on our system. So if I, for example, go to my directory that I have the handbook in this one, I can do code and then just full stop and that will open up visual studio code to that location there. So that's pretty handy and we're actually going to use that now to set up some helpful, um helpful command aliases here in the terminal that will make working with the handbook a little bit easier.

A

So what I'm going to do is I'm just going to go to cd tilde, which is my home directory, and then I'm just going to do code, dot, zs hrc, and what that will do is that will open up that zshrc file that we've been editing and down the bottom here you want to add this command here so I'll, just pop that down the bottom- and I will add this to the video description, so you can copy it easily, but basically it's alias handbook equals and then we have a bunch of different commands in here which we want to run in in succession whenever we want to develop the handbook.

A

So for me I want to go to my documents, projects.

A

Site www.gitlab.com handbook, then I want to open visual studio code to that location.

A

And after that I want to open my browser to the correct url for the handbook, and then I want to run bundle install which will install all the latest dependencies for the handbook and then finally, I want to actually run the handbook itself. So this is pretty handy. um You'll see once you've got that you can run source dot, tilde support, dot, zs hrc and then from here you can just basically run the command handbook and that will do all the things that we configured it to do in that file. So it's.

B

A

Up my visual studio code to the correct location in the handbook, yeah so handbook source, handbook, okay and then it's open up my browser to localhost 4567, which is where the handbook is hosted and then, if we open the terminal again, you'll actually see that it ran the handbook here. So you want to wait until you get this prompt here. That tells you to view your site and you can use any of your any of the urls that it recommends here. So we can either use this one.

A

This will dynamically update depending on the name of your computer, or you can use the one with the specific ip address or you can just use localhost like we've been doing localhost colin4567 and, as you can see, it's loaded the handbook here uh and yeah. That's basically it for that last step, just a really handy command that we can use to to basically run this quickly and easily at any time without having to run all those other commands and remember them as well. So this way you only have to remember the one command.

A

It's just handbook and that's it handbook.

A

So I hope this was a good tutorial that helped you set up. The handbook for local development on your computer feel free to give me any feedback in the comments or on slack and if you run into any issues while running any of this, just reach out to me to ask any questions and to get help.

A

So thank you very much for watching.