docker-documentation.md

Getting Started with Local Development for XRdocs

How to setup a local environment to edit XRdocs and view changes before pushing

There are two ways to set this up:

1. Docker Run Command (recommended)
2. Docker Compose File (has to be added into each repo locally)

The best way to set everything up for local edits would be to ensure that you have all of the repositories that you want to edit in a designated folder such as "xrdocs" located on your device. (Here, I have a folder created on my Desktop called XRdocs GitHub, with repos that have been cloned via git)

The steps are as follows:

1. Ensure that you have git downloaded on your system Git install guide
2. Ensure that you have Ruby version 2.6.10 or above installed Ruby Install guide
3. Create a folder and clone the repositories into your folder system
4. Download any IDE of your choice
5. Download Docker for your operating system and run it Docker Mac Install, Docker Windows Install
6. Run the test command for Docker (docker run hello-world) to ensure it is running properly
7. Change your directory into whatever part of the website you want to work on (Ex: programmability)
8. Once inside, you should be able to run the command listed

docker run --volume="$PWD:/srv/jekyll" -p 4000:4000 jekyll/jekyll:4.0 jekyll serve

for windows

docker run --volume="${PWD}:/srv/jekyll" -p 4000:4000 jekyll/jekyll:4.0 jekyll serve

After running, dependencies will be fetched, and after a minute or so, you will see a link to your locally hosted website

8. If you want to see the Docker run in the Docker Desktop App, you can open it and will see it temporarily running

One thing to note is that running with this command will show you the container it has created on the Docker Desktop application, and it will create a new container each time the command is rerun. However, since the container is just used to edit and then push to Github, you can delete the containers once you are done with your changes.

Compose File Method

The second method of setting up is a way to create a designated container for each repo you choose to edit rather than just a run command. Follow all of the above steps except for the Docker run command. Once completed, follow the steps below

1. Create a file called docker-compose.yml and copy the contents from this repository into your local repo (ex: programmability). To get it running with your choice of repository, copy the contents of the file above.
2. Once added, save the file, and in your terminal, run the command

docker-compose up

After dependencies, you should see this

3. If you want to check the container as well, you can check now in the Docker Desktop and will see a designated container for your repo (ex: programmability)

One thing to note with this method is that whenever you finish editing changes and want to push to the origin, you will constantly have to remove and add this compose file into each repo locally. It is recommended to follow the docker run method instead.

Troubleshooting

If you get one of the following errors:

1. Make sure that you have Ruby downloaded. You can check by running command

ruby -v

Then if a version appears, run

bundle add webrick

and retry. If you keep getting an error, run

sudo gem install bundler:2.3.25

or for windows run

gem install bundler

or whichever version of bundler it shows, then run

bundle add webrick

and retry

2. If you are a mac user and run into this issue, follow this guide to resolve Write Permissions Error

You should see the following in your terminal once successful

Once you open the link, you will be greeted with the webpage that you have chosen to edit (in this example, I have opened the programmability webpage)

Editing live

After opening the local host site, you are now able to edit anything via an IDE (using VScode in this example). Here we are editing the blog article of "Getting started with gNMI".

As you edit the file, once you are done with your changes and want to see them live, save the file you are working on locally. Once you save, you will see Jekyll refresh the website in your terminal

Once Jekyll has reloaded, simply refresh the local webpage and you will see your changes visible. Here we can see that the green highlights in our IDE indicate the changes we have made onto our webpage

Once you are satisfied with the changes, you can simply run do "ctrl + C" on mac or close the terminal to end the local webpage. After, you can push your changes to github in the respective repository, and your changes will load live on github <img pages. Sometimes your local IDE will show lots of changes being pushed to github, which were all done when dependencies were being updated alongside with the changes that you have made. Just make sure the changes you have made are visible and you can push to Github