Welcome to Gitlab CI with Docker and Sphinx’s documentation!

Setting up Docker

Docker is a platform for developers and sysadmins to develop, deploy, and run applications with containers. The use of Linux containers to deploy applications is called containerization. Containers are not new, but their use for easily deploying applications is.

Containerization is increasingly popular because containers are:

• Flexible: Even the most complex applications can be containerized.
• Lightweight: Containers leverage and share the host kernel.
• Interchangeable: You can deploy updates and upgrades on-the-fly.
• Portable: You can build locally, deploy to the cloud, and run anywhere.
• Scalable: You can increase and automatically distribute container replicas.
• Stackable: You can stack services vertically and on-the-fly.

Downloading Docker

Please visit the Docker Download link to download the latest Stable Docker Community Edition. There are downloads for use on local hardware (macOS, Win), Cloud (AWS and Azure), or Server (CentOS, DEbian, Fedora, or Ubuntu) I chose the macOS version.

Installing Docker

1. Open the installer you just downloaded from Docker’s site, and drag the application to the Applications Directory.
2. Double click on Docker.app and follow the directions posted on Docker’s site. They are good.

Getting Started after Docker install

Again, Docker’s site is well documented. Click here for some commands to get you started.

Kubernetes

Kubernetes is only available in Docker for Mac 17.12 CE and higher, on the Edge channel. Kubernetes support is not included in Docker for Mac Stable releases. To find out more about Stable and Edge channels and how to switch between them, see General configuration.

Docker for Mac 17.12 CE (and higher) Edge includes a standalone Kubernetes server that runs on your Mac, so that you can test deploying your Docker workloads on Kubernetes.

Gitlab setup

We set our sever up 3 years ago and did not document the steps :( BUT there is a article posted on Techrepublic.com that has all the steps covered. Jack even included instructions for adding SSH keys so your client can talk to the GitLab server.

Gitlab prep for CI

At this point you should have a functioning internal GitLab server. Next step is to create a project.

• Login to your Gitlab server.
• Click the green button to create a new Project.

1. Name your project
2. add a project description
3. Select a visability level. I picked Internal so anyone can contribute from our team.
4. Click create project

Creating .gitlab-ci.yml file

Now we have a project started and we can add a configuation file. The .gitlab-ci.yml file needs to be in the root of the project.

Note

YAML files are sensitive to indentation and spacing. Do not use tab to create spaces.

Touch and create a file called .gitlab-ci.yml

As you can see at the top of the image shows the .yml file is configured correctly. Super, it’s setup correctly, but how do we format it?

Note

There is a list of reserved keywords that cannot be used to name a job.

• image
• services
• stages
• types
• before_script
• after_script
• varibales
• cache

A job is defined by a list of paramaters telling the job what to do. In our case, we want to automate our document building. Now all the pieces are coming together.

• We have a gitlab server to host our projects containing code and documentation.
• We configured docker
• We setup our runner

We need to tell the runner what to “automate”, then the runner configures the docker contaniner with our .gitlab-ci.yml setup file. Every job needs to have a script, everything else is optional. In our case we use image to define what OS to load in our docker container. We chose alpine 3.6 which is a 5MB linux image. You can find tons of other Official repositories on Dockers site.

Pages: can be any word you want to describe the job such as “poopmonster” or “job1”. The educated call it arbitrary. The script: builds a fresh new envirnoment everytime. Previously these steps were manual. The CI also takes the built files and reloads them so all changes are immediatly available.

only: is a list of git refs for which job is created.

artifacts: Artifacts are a listing of files and directories where the successful job gets placed.

For more information about GitLab’s CI/CD configuration Click here.

Resources

Here are some links that I found useful.

Setting up the CI Runner for Gitlab

CI is Continuous intergration. Allows multiple people to work on the same project code in real time. Users create code, and upload/merge to the CI server many times throughout the workday. We are going to use a mac OS runner with our Gitlab server.

Note

Install the runner on a different host than your GitLab server.

1. Using terminal, download the binary package.

   sudo curl --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-darwin-amd64

2. Make the binary executable.

   sudo chmod +x /usr/local/bin/gitlab-runner

The following commands need to be run as the user that’s going to run the runner.

Install & Register the runner

Registering the runner binds the runner to your gitlab server. Make sure you install the runner on a different server than gitlab. You can only add the runner to your gitlab server if you are the admin of the GitLab server. Change to your home dir, install the runner and start the service.

• cd ~
• gitlab-runner install
• gitlab-runner start

The registration token is available at the admin/runners page.

Register

• gitlab-runner register
• Enter your Gitlab server url.
• https://my.server.com
• Enter your runner token.
• myS3crT0k
• Enter a description for the runner. If you can’t think of anything clever, it can be changed later in the UI.
• Next enter tags for the runner. Add as many as you would like, separated by commas.
• Enter the runner executor, we used docker
• Lastly we need to set the default image docker will use to build the envirnoment. We are using alpine:latest or alpine 3.6.

For other configurations and OS’s check out Gitlab’s Registering Runners Documentation.

Getting started with Sphinx

While attending and presenting at Mac Admin and Developer conference, MacAD.uk there was a session Your code should document itself! Embedding documentation into your Python projects that interested me. Awesome content presented by Bryson, I knew someday this would be useful. Working on a project, people were asking for documentation explaing our processes. Like any good project, we didn’t have any centralized methodical represenation of our thoughts, why not use Sphinx?

Sphinx

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

Install Sphinx

pip install sphinx

Make a directory somewhere to house your Sphinx projects.

mkdir /place/to/store/sphinx/docs

Change into your new directory.

cd /place/where/you/stored/sphinx/docs

Next start your project by running

sphinx-quickstart

Setting up your Sphinx project

After runnin sphinx-quickstart you should see the following output.

the default setting is in [] , press return for the default setting.

• Follow along with the promts that get outputted after your selections.
• Name the project
• Add the author and give the project a version number.

After completing all the prompts, I suggest creating the Makefile.

Congrats!! your first sphinx project is now started!

Working with your new Sphinx project

Navagate to the directory you setup for your documentation, and you should see something similar:

I use atom to edit the conf.py and index.rst files. There are plenty of editors you can choose from such as Sublime or BBedit.

• Open terminal and cd to the project directory.
• Next let’s create some .rst files to get our documentation started.
• While in the current project directory, touch mysphinxdirections.rst to create a Restructured Text file.

I’d create a couple of files to get started. For example, some docs used to create this project are called

• sphinxgettingstarted.rst
• GitLabsetup.rst
• runnersetup.rst

Avoid spaces, and try to keep the filename relevant to it’s function.

Open your editor and open your project. Open your .rst files and give them a title heading.

Make sure to save the files after adding the heading.

Next open your index.rst, and add the .rst files you touched in the terminal.

Note

Don’t add the file extension .rst to the index list.

At this point, we have

• Installed Sphinx.
• created a Sphinx project.
• created .rst files for our project.
• added .rst filenames to the index.rst

Now that we have some content configured, let’s build some documentation!

Building your Sphinx project

With the base of our project configured, we can generate some html content to view what we’ve started. Head back to your terminal application for the next step.

sphinx-build [options] <source directory> <output directory> [filenames]

If no output directory is listed, the output defaults to the source.

sphinx-build /path/to/my/sphinx/project/ html

will result in the following output.

Head back to the finder and locate your source directory and locate the new HTML directory.

Double click on the index.html file, and a web browser will display your project.

shpinx-build man page and additional options

Doesn’t that look purdy? I’m not a designer, and with minimal effort I have a resource that looks nice! Yes, yes that does look nice, why doesn’t my project look like that?

Sphinx Themes

A theme is a collection of HTML templates, stylesheets and other files. A theme keeps the HTML appearance consistant throughout the project making it look good.

In our example project, we are using sphinx_rtd_theme.

Setting up a Theme

Open your text editor and navigate back to the source directory. Locate the conf.py and open it for modification. Sphinx has some built in themes you can use setting the html_theme config value in your conf.py.

• Search conf.py for html_theme, enter the value sphinx_rtd_theme and save the script.

  

• Open terminal and install the theme pip install sphinx_rtd_theme

Save all your work.

Re-build your project, and refresh your browser and now you should see the blue and black theme.

Indices and tables

• Index
• Module Index
• Search Page