@@ -240,7 +240,7 @@ Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 >
A **guide** can be understood as a description of certain processes to achieve a particular objective. A guide brings you from A to B describing the characteristics of that process, but not necessarily going over each step. It can mention, for example, steps 2 and 3, but does not necessarily explain how to accomplish them.
- Live example: "GitLab Pages from A to Z - [Part 1](../user/project/pages/getting_started_part_one.md) to [Part 4](../user/project/pages/getting_started_part_four.md)"
- Live example: "[Static sites and GitLab Pages domains (Part 1)](../user/project/pages/getting_started_part_one.md) to [Creating and Tweaking GitLab CI/CD for GitLab Pages (Part 4)](../user/project/pages/getting_started_part_four.md)"
A **tutorial** requires a clear **step-by-step** guidance to achieve a singular objective. It brings you from A to B, describing precisely all the necessary steps involved in that process, showing each of the 5 steps to go from A to B.
It does not only describes steps 2 and 3, but also shows you how to accomplish them.
numerous purposes, to build, test, and deploy your app
...
...
@@ -22,10 +16,13 @@ from GitLab through
methods. You will need it to build your website with GitLab Pages,
and deploy it to the Pages server.
To implement GitLab CI/CD, the first thing we need is a configuration
file called `.gitlab-ci.yml` placed at your website's root directory.
What this file actually does is telling the
[GitLab Runner](https://docs.gitlab.com/runner/) to run scripts
as you would do from the command line. The Runner acts as your
terminal. GitLab CI tells the Runner which commands to run.
terminal. GitLab CI/CD tells the Runner which commands to run.
Both are built-in in GitLab, and you don't need to set up
anything for them to work.
...
...
@@ -37,7 +34,7 @@ need to understand just a few things to be able to write our own
with its own syntax. You can always check your CI syntax with
the [GitLab CI Lint Tool](https://gitlab.com/ci/lint).
**Practical Example:**
## Practical example
Let's consider you have a [Jekyll](https://jekyllrb.com/) site.
To build it locally, you would open your terminal, and run `jekyll build`.
...
...
@@ -387,7 +384,3 @@ in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the
[pulling specific directories from different projects](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/)
to deploy this website you're looking at, docs.gitlab.com.
- On this blog post, we teach you [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/).
|||
|:--|--:|
|[**← Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates**](getting_started_part_three.md)||
# GitLab Pages custom domains and SSL/TLS Certificates
-[Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md)
-[Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md)
-**Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates**
-[Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md)
## Setting Up Custom Domains - DNS Records and SSL/TLS Certificates
As described in the previous part of this series, setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages.
Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages.
These steps assume you've already [set your site up](getting_started_part_two.md) and and it's served under the default Pages domain `namespace.gitlab.io`, or `namespace.gitlab.io/project-name`.
### Adding your custom domain to GitLab Pages
## Adding your custom domain to GitLab Pages
To use one or more custom domain with your Pages site, there are two things
you should consider first, which we'll cover in this guide:
...
...
@@ -35,7 +28,7 @@ Let's start from the beginning with [DNS records](#dns-records).
If you already know how they work and want to skip the introduction to DNS,
you may be interested in skipping it until the [TL;DR](#tl-dr) section below.
### DNS Records
## DNS Records
A Domain Name System (DNS) web service routes visitors to websites
by translating domain names (such as `www.example.com`) into the
...
...
@@ -71,7 +64,7 @@ for the most popular hosting services:
If your hosting service is not listed above, you can just try to
search the web for "how to add dns record on <myhostingservice>".
#### DNS A record
### DNS A record
In case you want to point a root domain (`example.com`) to your
GitLab Pages site, deployed to `namespace.gitlab.io`, you need to
...
...
@@ -86,7 +79,7 @@ running on your instance).
#### DNS CNAME record
### DNS CNAME record
In case you want to point a subdomain (`hello-world.example.com`)
to your GitLab Pages site initially deployed to `namespace.gitlab.io`,
...
...
@@ -102,7 +95,7 @@ without any `/project-name`.
#### TL;DR
### TL;DR
| From | DNS Record | To |
| ---- | ---------- | -- |
...
...
@@ -118,7 +111,7 @@ domain. E.g., **do not** point your `subdomain.domain.com` to
`namespace.gitlab.io.` or `namespace.gitlab.io/`.
> - GitLab Pages IP on GitLab.com [has been changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) from `104.208.235.32` to `52.167.214.135`.
### Add your custom domain to GitLab Pages settings
## Add your custom domain to GitLab Pages settings
Once you've set the DNS record, you'll need navigate to your project's
**Setting > Pages** and click **+ New domain** to add your custom domain to
...
...
@@ -141,7 +134,7 @@ to your domain will respond with a 404.
Read through the [general documentation on GitLab Pages](introduction.md#add-a-custom-domain-to-your-pages-website) to learn more about adding
custom domains to GitLab Pages sites.
### SSL/TLS Certificates
## SSL/TLS Certificates
Every GitLab Pages project on GitLab.com will be available under
HTTPS for the default Pages domain (`*.gitlab.io`). Once you set
...
...
@@ -157,7 +150,7 @@ highly recommendable.
Let's start with an introduction to the importance of HTTPS.
Alternatively, jump ahead to [adding certificates to your project](#adding-certificates-to-your-project).
#### Why should I care about HTTPS?
### Why should I care about HTTPS?
This might be your first question. If our sites are hosted by GitLab Pages,
they are static, hence we are not dealing with server-side scripts
...
...
@@ -178,7 +171,7 @@ authentications and validations.
How about taking Josh's advice and protecting our sites too? We will be
well supported, and we'll contribute to a safer internet.
#### Organizations supporting HTTPS
### Organizations supporting HTTPS
There is a huge movement in favor of securing all the web. W3C fully
[supports the cause](https://w3ctag.github.io/web-https/) and explains very well
...
...
@@ -188,7 +181,7 @@ and would no longer accept unsecured connections. Recently, Mozilla published a
@@ -217,7 +210,7 @@ Their certs are valid up to 15 years. Read through the tutorial on
Regardless the CA you choose, the steps to add your certificate to
your Pages project are the same.
#### What do you need
### What do you need
1. A PEM certificate
1. An intermediate certificate
...
...
@@ -227,7 +220,7 @@ your Pages project are the same.
These fields are found under your **Project**'s **Settings** > **Pages** > **New Domain**.
#### What's what?
### What's what?
- A PEM certificate is the certificate generated by the CA,
which needs to be added to the field **Certificate (PEM)**.
...
...
@@ -240,7 +233,7 @@ are one of these cases.
- A public key is an encrypted key which validates
your PEM against your domain.
#### Now what?
### Now what?
Now that you hopefully understand why you need all
of this, it's simple:
...
...
@@ -257,6 +250,4 @@ just jumping a line between them.
regular text editors. Always use code editors (such as
Sublime Text, Atom, Dreamweaver, Brackets, etc).
|||
|:--|--:|
|[**← Part 2: Quick start guide - Setting up GitLab Pages**](getting_started_part_two.md)|[**Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages →**](getting_started_part_four.md)|
_Read on about [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md)_
-[Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md)
-**Part 2: Quick start guide - Setting up GitLab Pages**
-[Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md)
-[Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md)
## Setting up GitLab Pages
For a complete step-by-step tutorial, please read the
blog post [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/). The following sections will explain
what do you need and why do you need them.
# Projects for GitLab Pages and URL structure
## What you need to get started
To get started with GitLab Pages, you need:
1. A project
1. A configuration file (`.gitlab-ci.yml`) to deploy your site
1. A specific `job` called `pages` in the configuration file
that will make GitLab aware that you are deploying a GitLab Pages website
1. A `public` directory with the content of the website
Optional Features:
...
...
@@ -54,35 +47,26 @@ containing the most popular SSGs templates.
Watch the [video tutorial](https://youtu.be/TWqh9MtT4Bg) we've
created for the steps below.
1. Choose your SSG template
1. Fork a project from the [Pages group](https://gitlab.com/pages)
1. Remove the fork relationship by navigating to your **Project**'s **Settings** > **Edit Project**
1.[Fork a sample project](../../../gitlab-basics/fork-project.md) from the [Pages group](https://gitlab.com/pages)
1. Trigger a build (push a change to any file)
1. As soon as the build passes, your website will have been deployed with GitLab Pages. Your website URL will be available under your project's **Settings** > **Pages**
1. Optionally, remove the fork relationship by navigating to your project's **Settings** > expanding **Advanced settings** and scrolling down to **Remove fork relashionship**:
1. Enable Shared Runners for your fork: navigate to your **Project**'s **Settings** > **Pipelines**
1. Trigger a build (push a change to any file)
1. As soon as the build passes, your website will have been deployed with GitLab Pages. Your website URL will be available under your **Project**'s **Settings** > **Pages**
To turn a **project website** forked from the Pages group into a **user/group** website, you'll need to:
- Rename it to `namespace.gitlab.io`: navigate to **Project**'s **Settings** > **Edit Project** >**Rename repository**
- Rename it to `namespace.gitlab.io`: navigate to project's **Settings** > expand **Advanced settings** > and scroll down to**Rename repository**
- Adjust your SSG's [base URL](#urls-and-baseurls) to from `"project-name"` to `""`. This setting will be at a different place for each SSG, as each of them have their own structure and file tree. Most likelly, it will be in the SSG's config file.
> **Notes:**
>
>1. Why do I need to remove the fork relationship?
> Why do I need to remove the fork relationship?
>
> Unless you want to contribute to the original project,
> Unless you want to contribute to the original project,
Every Static Site Generator (SSG) default configuration expects
to find your website under a (sub)domain (`example.com`), not
...
...
@@ -152,11 +136,7 @@ example we've just mentioned, you'd have to change Jekyll's `_config.yml` to:
baseurl:""
```
### Custom Domains
## Custom Domains
GitLab Pages supports custom domains and subdomains, served under HTTPS or HTTPS.
GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS.
Please check the [next part](getting_started_part_three.md) of this series for an overview.
|||
|:--|--:|
|[**← Part 1: Static sites, domains, DNS records, and SSL/TLS certificates**](getting_started_part_one.md)|[**Setting Up Custom Domains - DNS Records and SSL/TLS Certificates →**](getting_started_part_three.md)|
-[Static websites and GitLab Pages domains](getting_started_part_one.md)
-[Forking projects and creating new ones from scratch, URLs and baseurls](getting_started_part_two.md)
-[Custom domains and subdomains, DNS records, SSL/TLS certificates](getting_started_part_three.md)
-[How to create your own `.gitlab-ci.yml` for your site](getting_started_part_four.md)
-[Static websites and GitLab Pages domains](getting_started_part_one.md): Understand what is a static website, and how GitLab Pages default domains work
-[Projects for GitLab Pages and URL structure](getting_started_part_two.md): Forking projects and creating new ones from scratch, understanding URLs structure and baseurls
-[GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md): How to add custom domains and subdomains to your website, configure DNS records, and SSL/TLS certificates
-[Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md): Understand how to create your own `.gitlab-ci.yml` for your site
