[Guide] Auto Deploy of Hugo via Gitea + Drone CI

randyjc

I was searching for a way to install Hugo together with Gitea and came across @fbartels excellent software to make this happen.

I ran into some bumps getting everything working properly, so I wanted to share my experience with this great community in hopes it will help others.

PS: As I mentioned on my site, if you find fbartels package useful, please consider making a donation to show your appreciation.

You can find the full guide at: https://cloudbasis.nl the guide below is without the extra added info of what what is per software.
Below is a condensed version of the guide without the extra background info per software:

Step-by-Step Guide

Let's get started with deploying Surfer and Gitea on your Cloudron server. Once complete, we'll set up the Drone CI solution to automate content deployment to your website via Drone > Gitea > Surfer.

Note: Never perform these steps on your Cloudron Server itself. Utilize any Linux-compatible device, like WSL for Windows, or any other Linux device. Please be aware that Windows support for this setup has not been tested by me; I use WSL as a recommended option.

Preparation

Choose a Linux-compatible device for this setup. In my case, I utilize a Docker LXC (Proxmox) from tteck to enjoy a fully dockerized environment available 24/7 when needed.

On the Docker LXC, install the following packages using apt:

docker-compose-plugin
git
jq
make
npm
hugo

Ensure that npm is updated to the latest version to avoid errors with Cloudron CLI:

npm install -g n
n stable

The Cloudron CLI can be installed on Linux using the following command:

sudo npm install -g cloudron

Docker Hub

Create yourself an account on Docker Hub. Remember your username as you will need that later in this guide.

Installation

Drone CI

Go to your desired folder on your Linux machine.
Login to your own Cloudron Instance via Cloudron CLI:
```
cloudron login my.yourowndomain.nl
```

Clone the repo and cd into it:

git clone https://github.com/fbartels/cloudron-drone-app && cd cloudron-drone-app

Do the magic with the following command:
```
DOCKER_REPO=your-docker-hub-user make install
```
Info: Because you used cloudron login, your Drone custom app will be deployed on your Cloudron server. The URL will be https://drone.yourowndomain.nl
Create an OAuth at your own Gitea environment.
See this for more information.
Back on your Linux machine (with this command, you go into the bash of your Drone instance at Cloudron):
```
make exec
```
Edit the following file:
```
nano .env
```

Fill in your URL, Client ID, and Secret from Gitea.

DRONE_GITEA_SERVER=https://git.yourowndomain.nl
DRONE_GITEA_CLIENT_ID=<see step 5>
DRONE_GITEA_CLIENT_SECRET=<see step 5>

The rest is already pre-filled; just don't touch it.

When you've successfully made your edits, you'll have to restart your Drone application. You can do this by executing:
```
cloudron restart
```

Runner

We have to make some edits to the original script start.sh to make it work.

nano runner/start.sh

#!/bin/sh

set -x

random_string() {
        LC_CTYPE=C tr -dc 'a-zA-Z0-9' < /dev/urandom | head -c32
}

update_env_file () {
    varname="$1"
    varvalue="$2"
    if ! grep -q "$varname" ./.env; then
        echo "$varname=$varvalue" >> ./.env
    else
        sed -i "/$varname/c $varname=$varvalue" ./.env
    fi
}

cloudron pull /app/data/.env .env

. ./.env

update_env_file DRONE_RPC_SERVER "https://$DRONE_SERVER_HOST"
update_env_file DRONE_RPC_HOST "$DRONE_SERVER_HOST"
update_env_file DRONE_RUNNER_CAPACITY "$(nproc)"
update_env_file DRONE_RUNNER_NAME "$(hostname)"

docker compose up -d

The above is a bit different from the original script; I've added the following line:

update_env_file DRONE_RPC_HOST "$DRONE_SERVER_HOST"

and I've replaced docker-compose with docker compose.

Save that; we will return to this later.

Surfer

Navigate to your Cloudron app: Surfer (example: https://blog.yourowndomain.nl).
Click on the link 'Manage your files in your browser'; this will redirect you to the admin panel of Surfer.
You can log in using the same credentials you use for your Cloudron environment.
On the top right, click on the three dots to open the menu. From there, click on 'Access Tokens'.
Click on the button 'Create Access Token' and save that somewhere in your notes because you'll need that in the next steps.

Gitea

If you haven't created any repo yet for your Gitea environment, I recommend you to do that now.
Once you've done that, you can use that repo to host your code from Hugo.

Example: randyjc/example_hugo - example_hugo - Gitea (cloudbasis.nl)

Drone CI

Go back to your Drone instance and activate the repository that you have just created on your Gitea environment.

Info: If you don't see your repo, click on SYNC (top right button).
Once it's activated, you'll be presented with the settings page.
Go to Secrets (not under Organization) and click on the button '+ NEW SECRET'.
Fill in the following:
- Name: surftoken
- Value: <see step 3 under surfnet>
- Make sure that 'Allow Pull Requests' is unchecked.
Click 'Create'.

Runner

Go back to your terminal and run the following command:

cd runner/ && ./start.sh

Info: When executing the script outside this folder, you'll get the error that it cannot find any configuration file.

Output should look like this:

+ cloudron pull /app/data/.env .env
+ . ./.env
+ DRONE_GITEA_SERVER=https://git.yourowndomain.nl
+ DRONE_GITEA_CLIENT_ID=<DELETED-FOR-SECURITY-REASONS>
+ DRONE_GITEA_CLIENT_SECRET=<DELETED-FOR-SECURITY-REASONS>
+ DRONE_RPC_SECRET=<DELETED-FOR-SECURITY-REASONS>
+ DRONE_DATABASE_SECRET=<DELETED-FOR-SECURITY-REASONS>
+ DRONE_SERVER_HOST=drone.yourowndomain.nl
+ DRONE_DATABASE_DATASOURCE=postgres://<DELETED-FOR-SECURITY-REASONS>?sslmode=disable
+ update_env_file DRONE_RPC_SERVER https://drone.yourowndomain.nl
+ varname=DRONE_RPC_SERVER
+ varvalue=https://drone.yourowndomain.nl
+ grep -q DRONE_RPC_SERVER ./.env
+ echo DRONE_RPC_SERVER=https://drone.yourowndomain.nl
+ update_env_file DRONE_RPC_HOST drone.yourowndomain.nl
+ varname=DRONE_RPC_HOST
+ varvalue=drone.yourowndomain.nl
+ grep -q DRONE_RPC_HOST ./.env
+ echo DRONE_RPC_HOST=drone.yourowndomain.nl
+ nproc
+ update_env_file DRONE_RUNNER_CAPACITY 2
+ varname=DRONE_RUNNER_CAPACITY
+ varvalue=2
+ grep -q DRONE_RUNNER_CAPACITY ./.env
+ echo DRONE_RUNNER_CAPACITY=2
+ hostname
+ update_env_file DRONE_RUNNER_NAME drone-ci
+ varname=DRONE_RUNNER_NAME
+ varvalue=drone-ci
+ grep -q DRONE_RUNNER_NAME ./.env
+ echo DRONE_RUNNER_NAME=drone-ci
+ docker compose up -d
[+] Running 1/0
 ✔ Container drone-agent  Running

If you run docker ps, you can see the container is running:

CONTAINER ID	IMAGE	COMMAND	CREATED	STATUS	PORTS	NAMES
3c7518132092	drone/drone-runner-docker:1.8	"/bin/drone-runner-d…"	1 minute ago	Up 1 minute	3000/tcp	drone-agent

Hugo

You can run Hugo on any machine you like, as long as you have git and Hugo installed.
For simplicity of this guide, I just use the exact same machine where I have the runner running as well.

Go to your terminal where you have Hugo and git available and cd to your desired location for your git repo.

Once there, follow these simple commands:

hugo new site mywebsitename && cd mywebsitename
git init
git remote add origin https://git.yourowndomain.nl/<user>/<your-git-repo>.git
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
echo theme = '"ananke"' >> config.toml
hugo new posts/hello-world.md
hugo -D

You'll now have to create the config file for your Drone CI instance so that the runner knows what to do with it:
```
nano .drone.yml
```

Paste the following inside that file:

---
kind: pipeline
name: blog_website
concurrency:
  limit: 1
steps:
  - name: submodules
    image: alpine/git
    commands:
      - git submodule update --init --recursive --remote
  - name: build
    image: plugins/hugo
    settings:
      hugo_version: 0.79.0
      extended: true
      validate: true
  - name: deploy
    image: 'fbartels/cloudron-surfer:5.12.2'
    environment:
      SURFTOKEN:
        from_secret: surftoken
    commands:
      - surfer --version
      - touch public/ # touch folder to avoid problems with timestamps
      - surfer put --token $SURFTOKEN --server blog.yourowndomain.nl ./public/* / 
    when:
      branch:
        - main
      event:
        exclude:
          - pull_request

Save & exit the file.

Follow these commands:

git add .
git commit -m "first push to Gitea"
git push origin main

If everything went well, you have now pushed all the files to your Gitea, and your Drone runner is probably already busy working on deploying it.

Success!

Navigate to your domain where you have deployed your Surfer instance, and you'll see that your Hugo website is now successfully deployed.

Sources

fbartels

Hi @randyjc,

this looks like a nice article and should help beginners get started with Hugo and Drone. Inspired by our chat yesterday, I have updated the project to use the latest Cloudron base image and the latest Drone release. I also added your script changes. Thanks for them.

girish

Great write up @randyjc !

@fbartels Now that woodpecker reached 1.0, do you know any major differences between woodpecker and drone?

fbartels

@girish I think the biggest difference is that Woodpecker does not support pipelines, so an existing configuration cannot be used 1:1. I found this blog which demonstrates the changes that need to be made.

I'm still quite happy with my Drone and haven't noticed anything missing, but if I wanted to change something with it I'd probably go for Gitea's native CI integration as it copies the Github action syntax.

robi

Nice, as I was reading this I was thinking how this could all run from the same Cloudron, where the additional docker host is replaced by an instance of a sysbox container that can run Docker-in-Docker (DinD).

robi

Just learned:
Forgejo development happens on Codeberg, which is itself running Forgejo and Woodpecker (for continuous integration). By “dogfooding” our code, we aim at being close to our users and serve them better.

fbartels

robi said in [Guide] Auto Deploy of Hugo via Gitea + Drone CI:

how this could all run from the same cloudron

It already could. Drone's runner (would be the same with Gitea or Woodpecker) is a simple go binary that just needs access to a local docker socket. It's just me running jobs on my installation, so there's no risk of exposing data to others by accessing the Docker socket.

And if you're serious about CI, you'll want optimised machines anyway (building in a ramdisk ftw), not running your CI jobs where their resources are competing with Wordpress & co. Being a simple binary that doesn't hold any local data also means you don't need to back up your runners, and since they access a central node, they don't even need internet access.

If you want to save costs, you can even let your developers run the runner on their local machines.

Cloudron makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server. Find out more or install now.

Cloudron Forum

[Guide] Auto Deploy of Hugo via Gitea + Drone CI

Step-by-Step Guide

Preparation

Docker Hub

Installation

Drone CI

Runner

Surfer

Gitea

Drone CI

Runner

Hugo

Success!

Sources