How to Setup Gitlab Pages [Part 1]: A Wordpress Alternative

Dhruv Kar | September 21, 2016 -- GET UPDATES OF NEW POSTS HERE

A. Who is this guide for?

This guide shows you how to set up a website that you can edit using HTML, CSS and Javascript. This guide is for someone who doesn’t code or know git, but has set up a Wordpress site or two, and is looking to learn how to build a simple, but working, site from scratch. If you already code, know git and are comfortable in the terminal, this will be (very) slow. Otherwise, strap in! In Part 1, we’ll go over how to setup Gitlab Pages for deploying a static site.

B. Why not Wordpress

Wordpress is a popular CMS to set up a site. It offers an easy way to build your site, but it usually comes with a hosting cost. It also obscures the details of how a site works. When you learn Wordpress, you learn the framework, but not the basics of a website works, which is perfectly fine for most cases. Since you’re here to learn, we’ll start from scratch. This is where Gitlab comes in. While its primary purpose is to manage code, it also offers free hosting for static sites.

Static sites are what you’d typically see as a small business’s marketing site, where it only displays static content like it’s hours, services, and team. A dynamic site generates pages as needed, like a site people log into and each person is shown personalized information. Most popular websites these days fall into this category. However, I’d argue that not everyone needs a dynamic website. If you’re looking to set up a basic site — personal portfolio, blog, documentation for a project — this method may be the most cost-effective for you.

C. Setup Gitlab Pages

Gitlab1 is used for managing code, but we’ll use it to host our static website.

  1. Go to https://gitlab.com/users/sign_in.
  2. Sign up for an account.
    Sign up for Gitlab
    Sign up for Gitlab
  3. After confirming your account, log in to your Gitlab account and create a new project. Note the project needs to be named YOURUSERNAME.gitlab.io:
    New Gitlab Project
    New Gitlab Project
  4. Once you see the new project page, click on “README”, write in what this project is for and click “Commit” at the bottom of the page.
    Create README
    Create README
    Write README description
    Write README description
  5. After creating a README, create a continuous integration file. The CI file will build the site everytime we push it to Gitlab.
    Create New File
    Create New File
    Name CI File
    Name CI File
  6. Fill the CI file with the code below. Gitlab builds a static site from everything in the folder named public, then commit the changes.
pages:
  script:
  - uname
  artifacts:
    paths:
    - public
  only:
  - master

D. Add a Custom Domain

Currently, your site lives at YOURUSERNAME.gitlab.io. If you want your site to be accessible at your own domain name, you can buy one at Google Domains. To set up a site at YOURDOMAIN.com, we’ll need to complete a few extra steps.

  1. At your registrar (Google Domains, GoDaddy, etc.) setup a CNAME pointing to www.YOURDOMAIN.com
  2. At your registrar, (Google Domains, GoDaddy, etc.) setup an A record pointing to 104.208.235.32. This is the IP address for Gitlab Pages.
  3. Add your domain name (both with WWW, and without) to Gitlab Pages. Click the gear icon on the top right and click Pages.
    Click Pages in Settings
    Click Pages in Settings
    Click New Domain on the top right.
    Add New Domain
    Add New Domain
    Enter in your domain name starting with www. Then click Create New Domain on the bottom left.
    Enter Domain Name
    Enter Domain Name
    Following the same steps above, add the non-WWW version of your domain as well, so step A will contain only YOURDOMAIN.tld. This way, your website will be available at both URLS. It should look like this:
    Both Domains Added
    Both Domains Added

E. Test It

In your Gitlab project, add a new folder called public. This is the folder that will be served by Gitlab Pages, meaning files placed in this folder will show up on YOURDOMAIN.com (or YOURUSERNAME.gitlab.io if you haven’t setup a custom domain). So your project should now contain a folder named public, a README.md, and a .gitlab-ci.yml file.

Current State of Repository
Current State of Repository

Special Files

Files named 404.html and index.html are treated specially.

  • index.html: These are treated as the homepage of the directory they’re in. The index.html file in the public folder will be the homepage of your website.
  • 404.html: These are displayed when the user tries to access a page that doesn’t exist. You just need one of these, and it should be in the root (public) folder.

In the public folder, add a new file called ‘index.html’. Edit index.html and add:

This is my website

Edit Index File
Edit Index File

Click Commit Changes at the bottom. Once the CI file runs through and shows passed under the Project tab, you should be able to access this on YOURUSERNAME.gitlab.io and your own domain (if you set it up).

CI Passed
CI Passed

At this stage, your website should look like this. Yay.

Website
Website

In Part 2, we’re going to go over adding more HTML, some CSS and Javascript to start building a functional site. In the meantime, check out HTML Basics and see if you can create more pages.


  1. Github, a competitor, also offers free static site hosting. [return]
comments powered by Disqus