Installing GitLab on Your Own Server (Part 6) – Configure NGINX for Pages

Now I create a NGINX server as TLS termination proxy for the GitLab pages.

I only want to serve a small number of projects/groups and want to use Let’s Encrypt for the certificates. Together with my provider settings I’m not able to use wildcard certificates from Let’s Encrypt.

So I set up a dedicated domain for each group I want to serve and do not serve other groups.

In this document I will use the domain as pages domain.

So the first step is to enable the pages in GitLab. For this the following settings are needed in the file /etc/gitlab/gitlab.rb:

pages_external_url ""
gitlab_pages['enable'] = true
gitlab_pages['listen_proxy'] = "localhost:8090"

This sets the external URL and enables GitLab pages to listen on port 8090.

Configure NGINX

Next I show how to set up the NGINX web server to serve all pages for a group. I use the group name sample for the example.

My configuration file looks like

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_tokens off;

    ssl on;
    ssl_certificate /etc/ssl/cert/;
    ssl_certificate_key /etc/ssl/private/;
    ssl_session_timeout 5m;
    ssl_protocols TLSv1.2;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
    ssl_session_cache shared:SSL:50m;
    ssl_dhparam /etc/ssl/cert/;
    ssl_prefer_server_ciphers on;

    # 1 week HSTS
    add_header Strict-Transport-Security "max-age=604800; includeSubDomains;";
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Robots-Tag noarchive;
    add_header X-Download-Options noopen;
    add_header X-Permitted-Cross-Domain-Policies none;

    access_log  /var/log/nginx/access.log;
    error_log   /var/log/nginx/error.log;

    location / {
        proxy_set_header    Host                $http_host;
        proxy_set_header    X-Real-IP           $remote_addr;
        proxy_set_header    X-Forwarded-Ssl     on;
        proxy_set_header    X-Forwarded-For     $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Proto   $scheme;
        proxy_pass http://localhost:8090/;


Please note that you have to change your hostname in line 4.

Next you have to change the lines 8, 9 and 14 to point to your own key (required), certificate (required) and dhparams (optional).

In line 12 you can define the TLS ciphers that you want to use for your server. You can see all supported ciphers with openssl ciphers (see NGINX documentation).

Last you should change line 18 to fit your own HSTS settings.

If you set up GitLab pages like this you have to set up a virtual host for each group and each user that wants to use pages. This is only feasible if you only have a small number of groups and users.

Differences between GitLab pages and GitHub pages

Serving GitLab pages is different to serving GitHub Pages.

In GitHub you check in your pages into your repository, either as a separate branch (gh-pages) or into your master branch. You can also check in markdown which gets transformed by GitHub.

In GitLab you have to publish your pages in a different way. You have to put all your HTML code into a folder named public during your build and can simply publish this.

The creation of the HTML code is completely up to you.

This is the end of my series to set up GitLab for your own use. Perhaps some more posts will follow with Java related topics.



2 thoughts on “Installing GitLab on Your Own Server (Part 6) – Configure NGINX for Pages

  1. Pingback: Installing GitLab on Your Own Server (Part 1) – Installation | Blog at

  2. Pingback: Installing GitLab on Your Own Server (Part 3) – Install gitlab-runner | Blog at

Leave a Reply

Your email address will not be published. Required fields are marked *