Usage

Deploying a Hugo site

Steps

First on your computer install Hugo. Then follow this simple steps.

1. Create a gitea repository.
2. $ hugo new site NAMEOFREPOSITORY
3. Move to this folder and set the remote origin branch. $ cd NAMEOFREPOSITORY $ git remote set-url origin https://YOURGITEASITE/YOURUSER/REPOSITORY.git

4. Now,you have to download a Hugo Theme. In this case, we are installing WhiteClub’s Hugo Theme.

   $ git clone git clone https://git.radio.clubs.etsit.upm.es/Whiteclub/Whiteclub-Hugo-Theme.git themes/whiteclub
   

   Then, from themes/whiteclub/exampleSite, copy all files and folders to the root folder of your Hugo site and change the fields on config.tml as you like.

• (Optionally) Creating nginx configuration and setup SSL certificate with Letsencrypt.

  With WhiteClub’s dependencies we are able to create the skeleton of our Hugo Site configurations. And then, update our custom full ansible playbook, with this configurations.

  With letsencrypt-request we can set our Hugo Site subdomain with Let’s Encrypt, like this. With add_nginx_conf we can create the basic configuration for our subdomain pointing our hugo public files.

  Example of a basic subdomain setup for an hugo page:

## Hugo site conf files
- name: Get subdomain Let's Encrypt certificate
  hosts: all
  become: true
  vars:
    domain: "{{ hugo_subdomain }}"
    letsencrypt_renew_hook: /usr/sbin/service nginx reload
  roles:
    - role: letsencrypt-request
      tags: letsecrypt_request

- name: Configure nginx for hugo site
  hosts: all
  become: true
  vars:
    domain: "test.{{ base_domain }}"
  roles:
    - role: add_nginx_conf
      tags: proxy

• (Optionally) Setup Drone to deploy Hugo Sites. In order to update the Hugo site when there is a new commit on remote repository, we will use Continuous Integration with Drone io (deployed with WhiteClub).

  This step can be done in many ways. We propose to:

  1. [On remote server] Create an user on the server called hugo, in charge of deploying hugo sites.
  2. [On remote server] Create a pair of SSH keys (public and private). We will use it to access the server from the drone containers.
  3. [On remote server] Create a folder on ~/YOUTHUGOSITE
  4. [On remote server] Create a symbolic link between the PATH on nginx conf (/var/www/HUGOSITE) and the folder created on point 3. This way, hugo user can only write files on his home, and files are public for nginx.
  5. [On your gitea repository] Create a drone configuration file called .drone.yml on repository. This is the recipe that we use:

kind: pipeline
name: default

clone:
  depth: 50

steps:
- name: submodules
  image: docker:git
  commands:
  - git submodule update --init --recursive

- name: build
  image: orus/hugo-builder
  commands:
    - hugo

- name: deploy
  image: orus/concourse-scp-resource
  environment:
    USER:
      from_secret: ssh_username
    SCP_KEY:
      from_secret: ssh_hugo_key
    PORT:
      from_secret: ssh_port
    HUGO_PATH:
      from_secret: hugo_path
    HOST:
      from_secret: ssh_host
  commands:
    - mkdir -p ~/.ssh
    - echo "$SCP_KEY" | tr -d '\r' > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa && chmod 700 ~/.ssh
    - eval "$(ssh-agent -s)"
    - ssh-add ~/.ssh/id_rsa
    - ssh-keyscan -p $PORT -H $HOST >> ~/.ssh/known_hosts
    - scp -r -P $PORT public/* $USER@$HOST:$HUGO_PATH
  when:
    branch:
    - master
    event:
      exclude:
      - pull_request

Go to your Drone site and setup environment variables of your repository as follow:

• ssh_username: Created before as hugo.
• ssh_hugo_key: Private ssh key of hugo user on remote server, stored on ~/.ssh/id_rsa
• hugo_path: Where will be deployed public folder of Hugo site (a simbolic link from /var/www). See point 3 and 4.
• ssh_host

With this configurations we will have an hugo page fully integrated with Gitea and Drone.

An example could be the webpage of Radioclub. Where hugo files are here, and drone CI here.