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
