How to create docs.domain.com 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 gitlab.com. You can deploy Gitlab easily on the servers of Yourwebhoster.eu 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 docs.wedevelop.coffee with the name you want to use for your documentation URL and yourgitlab.com 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 {
   server_name docs.wedevelop.coffee;
   location / {
      proxy_pass https://yourgitlab.com/;
      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 docs.wedevelop.coffee):

certbot --nginx -d docs.wedevelop.coffee

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 wedevelop.coffee).

pages_external_url "https://wedevelop.coffee/"

Gitlab normally wants a wildcard domain; but we only want to run Gitlab on docs.wedevelop.coffee. 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 https://github.com/lord/slate.git 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

.gitlab-ci.yml

with the following content:

pages:
  stage: deploy
  image: ruby:2-stretch

  before_script:
    - apt-get update
    - apt-get install nodejs -y
    - bundle install
  script:
  - bundle exec middleman build
  - mv build public
  artifacts:
    paths:
    - public
  only:
  - master