How to create with Gitlab pages CentOS 7

With Gitlab you can create your own pages with the Gitlab runner and Gitlab pages feature. Both features are free in the CE version of Gitlab. In this blog I will explain how we have automated the deployment of our documentation to the public using Gitlab pages  onCentOS 7 and a Nginx reverse proxy. To document our services; we use Slate. In total we are using three different servers for this setup; but you can opt for less servers. Please note that you can not use this for repositories hosted on You can deploy Gitlab easily on the servers of instead.

First; we’ll need a Gitlab server and Gitlab runner. Gitlab has documented the installation very well and the Omnibus installer makes it easy to manage your Gitlab installation. In this setup we need a runner that supports Docker; so when you register the runner; make sure that you choose Docker as Executor and that you add the runner as a shared runner.

Install Nginx reverse proxy and certbot

In this example I use CentOS 7 on a separate server from the Gitlab server and Gitlab runner. You can use any OS you want but you will need to adapt the commands a little bit. You can use Gitlab itself to run the pages from; however for security reasons I have added a ‘dumb’ reverse proxy in front of Gitlab. Install Nginx and certbot (to encrypt the connection):

yum install epel-release -y
yum install nginx certbot-nginx -y
systemctl enable nginx

Open /etc/nginx/default.conf and remove the server { … }  part.

Create the file /etc/nginx/conf.d/gitlab.conf and enter the following data. Replace with the name you want to use for your documentation URL and with the domain of your Gitlab installation including https (if you are not using https for your Gitlab installation; make sure that you add this).

server {
   location / {
      proxy_redirect off;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_max_temp_file_size 0;
      client_max_body_size 10m;
      client_body_buffer_size 128k;
      proxy_connect_timeout 90;
      proxy_send_timeout 90;
      proxy_read_timeout 90;
      proxy_buffer_size 4k;
      proxy_buffers 4 32k;
      proxy_busy_buffers_size 64k;
      proxy_temp_file_write_size 64k;
    listen 80;


Execute the following command (replace

certbot --nginx -d

Follow the instructions and make sure that you agree with the agreement. Also; make sure to allow a redirect to https by certbot.

Configure Gitlab for Gitlab pages

Open /etc/gitlab/gitlab.rb and uncomment pages_external_url. Update the value with the main domain (in this case

pages_external_url ""

Gitlab normally wants a wildcard domain; but we only want to run Gitlab on To do so, we have created a group called docs in Gitlab and every documentation project will be hosted in this group.

To finish the configuration of Gitlab execute the following commands. These will reconfigure Gitlab properly.

gitlab-ctl reconfigure
gitlab-ctl restart gitlab-pages

Start with Slate

Slate is a great tool to document your application with. First clone the Slate repository to your computer.

git clone project-name
cd project-name

Now; update the source with the content that you want to publish for your application. Or go to the next step if you just want to make sure that it works.
Add the file


with the following content:

  stage: deploy
  image: ruby:2-stretch

    - apt-get update
    - apt-get install nodejs -y
    - bundle install
  - bundle exec middleman build
  - mv build public
    - public
  - master
Save the file and commit the changes to your Git repository. Push the changes to your repository. Gitlab will now automatically generate the docs and publish them. This will take a few minutes since I did not create an optimised Docker container yet; but for now this will do. Oh; are you wondering why I would move the build folder to public? Well, as it turns out there is a permission error with Docker and Gitlab. Moving the folder fixes this.
By | 2018-05-26T17:24:07+00:00 May 25th, 2018|Documentation|