DEV Community: LoadBalancing.xyz

Blogging with Hugo and GitLab (4): HTTPS with Let's Encrypt

LoadBalancing.xyz — Sat, 04 May 2019 00:00:00 +0000

The default HTTPS support by GitLab will be unavailable with custom domains. Fortunately, there is the solution to add HTTPS back for free.

Why HTTPS?

HTTPS (HTTP over TLS or HTTP over SSL) is more secure than HTTP. Today many browsers will mark a website as insecure if it's visited via HTTP instead of HTTPS. I think that's important for personal bloggers as you don't want people to think they are exposed to security risk by visiting your blog website.

Why Let's Encrypt?

In order to equip your website with HTTPS, you need to acquire a SSL/TLS certificate from a certificate authority (CA) that is trusted by browsers. The good thing is that free certificates are available. For example:

CAcert is more in the Linux world while certificates issued by it are still not trusted by most browsers.
Cloudflare (btw, they own an interesting domain https://one.one.one.one) offers free certificates, but it might not be really free if you go with full features.
Let's Encrypt provides full-feature free certificates which are valid for 90 days and renewable.

Overall, Let's Encrypt is the best.

Environment

macOS Sierra 10.12.6.

Obtain a Let's Encrypt certificate

Install Homebrew in macOS.
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Install CertBot.
brew install certbot
Request a certificate. Though optional, it's recommended to provide an email to receive notifications (e.g., certificate expiration). Here we request the certificate for both root domain and sub-domain.
sudo certbot certonly -a manual -d loadbalancing.xyz -d www.loadbalancing.xyz --email example@email.com
It's then followed by several steps:
- Type A to agree with their terms of service.
- Type either Y or N depending on if you want to receive news from Let's Encrypt.
- Type Y to agree with logging your IP.
Then pause here (don't press Enter). Follow the instruction to create a file containing the data specified and commit it to your repository.
cd your_repository/static
mkdir -p .well-known/acme-challenge/
vi the_specified_file_name
The file need to be available at:
http://loadbalancing.xyz/.well-known/acme-challenge/the_specified_file_name
Now press Enter. It will generate and save the certificate and key to local. Record their content which will be used in the next step.
sudo cat /etc/letsencrypt/live/loadbalancing.xyz/fullchain.pem
sudo cat /etc/letsencrypt/live/loadbalancing.xyz/privkey.pem

Add the certificate to GitLab

Add the certificate and key to your website.

"Setting" > "Pages".

For each domain (root and sub-domain), click "Details" > "Edit".
Copy and paste the certificate into the first field Certificate (PEM).
Copy and paste the private key into the second field Key (PEM).
Let traffics be automatically directed to HTTPS.

Select "Force HTTPS (requires valid certificates)".

Click "Save".

After a few minutes, you will be able to visit your website via HTTPS. You may also want to update the base URL in config.toml.

Renewal

As mentioned earlier, Let's Encrypt certificates expire every 90 days and you will have to renew them periodically. To renew certificates:

sudo certbot renew

Alright, after two months I realized the above renewal just doesn't work. The following error is given:

"Attempting to renew cert (loadbalancing.xyz) from /etc/letsencrypt/renewal/loadbalancing.xyz.conf produced an unexpected error: The manual plugin is not working; there may be problems with your existing configuration.

The error was: PluginError('An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively.'). Skipping."

Looks like the only way of renewal is to manually redo the whole procedure, which I don't think is gonna be sustainable. Fortunately, someone figured out a way of auto renewal with GitLab and I will update my experience of trying that in the next post.

Blogging with Hugo and GitLab (3): Custom Domains

LoadBalancing.xyz — Sat, 06 Apr 2019 00:00:00 +0000

Give your blog website a custom domain to make it more professional and/or more fun.

Top-level domain

A top-level domain (TLD) is the last label of a domain name, for example, "com" of "www.example.com". For that same example, "example" is a second-level domain. With your blog website created and hosted in GitLab, it's associated with the second-level domain "gitlab.io" and can be visited at https://username.gitlab.io.

There is a wide variety of top-level domains today. Besides the most known ones like ".com" and ".net", you have the choice of other new interesting domains for your style such as ".lol", ".cat" and ".nyc". Some domains look strange to me, for example, ".fail" and ".wtf", and I wonder how they can be used (that said, there is one good example I really like, Algorithms.wtf, by a professor in UIUC).

Could top-level domains be free? Yes, but you only have five options and you won't be able to own it (though you can use it). Domains can be affordable as long as it's not a premium/popular name. Often time you can get one with around ten bucks for a year. It may even have discount for the first year ended up with less than one buck. To begin with, you will need to choose a domain name registrar. Here NameSilo is recommended.

Why NameSilo?

By looking around, I found NameSilo to be a domain name registrar with very good reputation (though its website looks old-fashioned). Its main advantage is the price--not only cheap, but also transparent. The price listed is what you pay (which may not be always true for other domain name registrars). For a new registration, there is the coupon NamesiloOneDollar to get $1 discount. Note that NameSilo does not offer SSL/TLS certificates (which means your website can only be visited at http:// but not https://). Fortunately, there are options that offer secure SSL/TLS for free.

Register a domain at NameSilo

To register a domain:

Go to NameSilo and search the name you would like to get.
Select the top-level domain (e.g., .com) you prefer and click "REGISTER CHECKED DOMAINS".
Set the configuration options as below:
- "Service Link": None (default)
- "NameServers": (leave it)
- "Auto-Renew": No/Yes
- "Privacy Setting": WHOIS Privacy
- "Set all years to": 1/2/3/.../10 Note that for a domain with the first-year pricing promotion, the limit for registrations is 1 year. Upon registration, you will then be able to extend it for up to 10 years with the regular price.
Enter the coupon NamesiloOneDollar and click "Submit" to apply.
Click "CONTINUE -->" and choose the payment.

Link the domain with your website

The rationale behind the linkage of a domain and your website is to rely on the Domain Name System (DNS) which maps the domain to the IP address where the website is served. Configuration is needed on both sides:

Add the custom domain to GitLab.
Add the DNS records to the domain name registrar (e.g., NameSilo) and direct them to GitLab.

Add a custom domain to GitLab

Disable the forcing of HTTPS, since NameSilo does not provide SSL/TLS certificates.
"Settings" > "Pages".
Unselect "Force HTTPS (requires valid certificates)".
Click "Save".
Add the root domain (e.g., loadbalancing.xyz).
"Settings" > "Pages" > click "New Domain".
"Domain": loadbalancing.xyz
"Certificate (PEM)": (leave it blank)
"Key (PEM)": (leave it blank)
Click "Create New Domain".
GitLab will then generate a DNS TXT record content (will be used later) like:
_gitlab-pages-verification-code.loadbalancing.xyz TXT gitlab-pages-verification-code=...
Add the sub-domain (e.g., www.loadbalancing.xyz).
"Settings" > "Pages" > click "New Domain".
"Domain": www.loadbalancing.xyz
"Certificate (PEM)": (leave it blank)
"Key (PEM)": (leave it blank)
Click "Create New Domain".
GitLab will then generate a DNS TXT record content (will be used later) like:
_gitlab-pages-verification-code.www.loadbalancing.xyz TXT gitlab-pages-verification-code=...

Add DNS records to NameSilo

Open the control panel of NameSilo.
Click "domain manager".
Click the domain you want to configure.
Click "DNS Records: Update".
Remove all existing DNS A and CNAME records.
For the root domain (e.g., loadbalancing.xyz):
Create a new A-type record.
"HOSTNAME": (leave it blank)
"TYPE": A
"ADDRESS / VALUE": 35.185.44.232 (GitLab's IP address)
"DISTANCE/PRIO" : NA
"TTL": 3603
click "SUBMIT".
Create a new TXT/SPF-type record.
"HOSTNAME": _gitlab-pages-verification-code
"TYPE": CNAME
"ADDRESS / VALUE": gitlab-pages-verification-code=...
"DISTANCE/PRIO" : NA
"TTL": 3603
click "SUBMIT".
For the sub-domain (e.g., www.loadbalancing.xyz):
Create a new CNAME-type record:
"HOSTNAME": www
"TYPE": CNAME
"ADDRESS / VALUE": username.gitlab.io
"DISTANCE/PRIO" : NA
"TTL": 3603
click "SUBMIT".
Create a new TXT/SPF-type record:
"HOSTNAME": _gitlab-pages-verification-code.www
"TYPE": CNAME
"ADDRESS / VALUE": gitlab-pages-verification-code=...
"DISTANCE/PRIO" : NA
"TTL": 3603
click "SUBMIT".

Here we use different DNS records for the root domain and sub-domain (DNS A record and DNS CNAME record respectively). The DNS TXT records are required by GitLab to verify the domain's ownership.

After a couple of minutes, you will be able to visit your website from the new domain.

Blogging with Hugo and GitLab (2): Local Development Setup

LoadBalancing.xyz — Sun, 24 Mar 2019 00:00:00 +0000

While you can edit pages online in GitLab (e.g., through Web IDE, which also allows to preview Markdown pages), a local development environment of Hugo provides the best support of "what you see is what you get".

Environment

macOS Sierra 10.12.6.
Hugo v0.54.0.

Create a local repository

With the website repository hosted on GitLab, we can clone the repository to local.

Clone your website repository to local.

git clone https://gitlab.com/username/username.gitlab.io.git

Configure your GitLab account email within the local repository, which will be used as the identification for all change commit.

git config user.email "example@email.com"

The updated account information can be verified in .git/config:

[user]                                                                           
email = example@email.com

Install Hugo to local

Install Homebrew in macOS.

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Install Hugo.

brew install hugo

Verify the installation by viewing the Hugo version:

hugo version

Start the Hugo server

Start the Hugo server with "drafts" enabled, which will show all pages including drafts on the local server.

hugo server -D

Now you will be able to view your website locally at: http://localhost:1313.

The Hugo server will keep running until you press Ctrl+C to stop it. Any saved changes will be immediately reloaded.

Blogging with Hugo and GitLab (1): Quick Start

LoadBalancing.xyz — Sat, 23 Mar 2019 00:00:00 +0000

Building your own blog website is easy today. With only a few steps, you will be able to create your own blog website which can be visited at https://username.gitlab.io.

Why Hugo?

If your goal is to build a static website (which is good enough for personal blogs), there are several solutions today to help make such process easy and automatic. Basically what you need to do is to write some Markdown docs and they will help you convert them into static HTML files. Among those options, Hugo is known to be the fastest one in terms of static page building, since it's written in Go with compilation while the others are based on interpretation.

Why GitLab?

GitLab offers free service of GitLab Pages for hosting static websites. The GitLab Pages service also provides native support for Hugo, which makes it extremely easy and convenient to build and deploy your webiste without replying on any other third-party supports.

If you are convinced, the first step is to create an account in GitLab. Note that your username in GitLab will be the sub-domain name of your website's URL such as https://username.gitlab.io.

Create your website repository

Since our goal is Hugo+GitLab, the easiest way is to fork the official Hugo repository in GitLab.

Go to Hugo's repository on GitLab
Login with your GitLab account.
Fork this repository.

Some further configuration:

Remove the forking relationship, which won't be necessary unless you want to contribute back to the upstream project.
"Settings" > "General" > "Advanced" > click "Expand"
Click "Remove fork relationship".
Rename the repository, so it will be linked to your website's URL https://username.gitlab.io.
"Settings" > "General" > "Advanced" > click "Expand" > "Rename repository"
"Project name": username.gitlab.io
"Path": username.gitlab.io
Click "Rename project".
Mark your repository as private--if you only want people to visit your website through the URL, but not be able to view your repository.
"Settings" > "General" > "Visibility, project features, permissions" > click
"Expand"
"Project visibility": Private
click "Save changes".
Update the base URL in config.toml.

diff --git a/config.toml b/config.toml
--- a/config.toml
+++ b/config.toml
@@ -1,4 +1,4 @@
-baseurl = "https://pages.gitlab.io/hugo/"
+baseurl = "https://username.gitlab.io"

After a couple of minutes, you will be able to visit your website at https://username.gitlab.io.