Background

Since https://bitcron.com/, where I had been hosting my blog, couldn’t update certificates, and their Let’s Encrypt auto-renewal script was broken (is this site going to shut down? (whispers)), I decided to take some time to migrate my blog to a pure static blog.

I had previous experience with hexo, plus the Node ecosystem is exceptionally rich for personal blogs (lots of third-party plugins available), so I decided to migrate.

After Github was acquired by Microsoft, although its CEO immediately became a billionaire, my goodwill towards it dropped to rock bottom. I only kept a few small open source projects and previously forked projects there, and stopped the paid plan for private repos. Now I’ve moved most of my code and private repos to GitLab. So the initial tech choice of GitLab Pages + hexo was settled.

Smooth Progress

First, following hexo’s official documentation step by step, I set up the main framework. Combined with GitLab CI for automatic static page generation and deployment, everything seemed surprisingly simple.

Problem Encountered

In GitLab’s pages options, it’s easy to find options for binding domains and setting up certificates. I installed Let’s Encrypt’s CLI tool certbot on my VPS and followed the official documentation:

certbot certonly --manual -d www.ogura.io

Next, next, until it stopped at the step requiring website ownership verification:

Access http://www.ogura.io/.well-known/acme-challenge/JDbJQP50-rI3LgKGLy7U7EhOkSxr73P0bP2UeTIh1yE to get a static file with specified content.

Serving static files on my own VPS couldn’t be simpler, but how do you do it with GitLab + hexo?

After experimentation, I learned that files in the source/ folder are directly placed in the public/ folder, but the special case is that .well-known is a hidden folder, and hexo generate ignores hidden files and folders when generating static files.

GitLab pages gave an example solution for Jekyll using an xxx.md file with content:

---
layout: null
permalink: /.well-known/acme-challenge/5TBu788fW0tQ5EOwZMdu1Gv3e9C33gxjV58hVtWTbDM
---

5TBu788fW0tQ5EOwZMdu1Gv3e9C33gxjV58hVtWTbDM.ewlbSYgvIxVOqiP1lD2zeDKWBGEZMRfO_4kJyLRP_4U

But in hexo (at least with the next theme, there’s no null layout), and the generated link has a .html suffix, which doesn’t pass verification.

After messing around with custom layouts for a long time without success, I finally added a manual copy command in .gitlab-ci.yml, and it worked. (Wasted half an hour on layout templates = =)

# This file is a template, and might need editing before it works on your project.
# Full project: https://gitlab.com/pages/hexo
image: node:6.10.0

pages:
  script:
  - npm install
  - ./node_modules/hexo/bin/hexo generate
  - /bin/cp -rv static/.well-known public/
  - ./node_modules/.bin/hexo algolia
  artifacts:
    paths:
    - public
  cache:
    paths:
      - node_modules
    key: project
  only:
  - master