article about my own github pages alternative
This commit is contained in:
Joshua Seigler
parent
78034d1de2
commit
ed692e5587
1 changed files with 300 additions and 0 deletions
300
site/posts/2025-06-15-replacing-github-pages.md
Normal file
300
site/posts/2025-06-15-replacing-github-pages.md
Normal file
|
|
@ -0,0 +1,300 @@
|
|||
---
|
||||
title: My Very Own GitHub Pages
|
||||
slug: my-very-own-github-pages
|
||||
description: How to self-host Forgejo and automatically serve your web build branches with SSL
|
||||
---
|
||||
|
||||
I recently started self-hosting [Forgejo](https://forgejo.org/), but I wanted something to replace GitHub pages, which has been very convenient for publishing little website projects. My server runs Debian, so I decided to use [webhook](https://github.com/adnanh/webhook) and [Caddy](https://caddyserver.com/). I'm very happy how it turned out.
|
||||
## The result
|
||||
When I push a `gh-pages` branch to any public repository on my Forgejo instance, the name of the repo is used as a domain name (e.g. [marklink.pages.seigler.net](https://marklink.pages.seigler.net/)) and the branch contents are automatically served with SSL. If I push updates to the branch, they are automatically published. If the branch or repo is deleted, the site is taken down.
|
||||
## How to do it
|
||||
### Debian server preparation
|
||||
In case you don't have a basic server setup routine yet, this is a good start:
|
||||
- Change the default root password
|
||||
- Create a new user, add it to the sudo group. In my examples below the user is `joshua`.
|
||||
- Use `ssh-copy-id` to install your ssl pubkey for easier login
|
||||
- Disable/lock root's password
|
||||
- Disable root login over ssh and change the SSL port number. Pick a new port lower than 1024.
|
||||
- Edit your local `~/.ssh/config` so you don't have to specify the port number every time you connect.
|
||||
- On the server, install and enable `ufw` and `fail2ban`. In addition to allowing your custom SSL port, be sure to enable ports 80 and 443 with `sudo ufw allow "WWW Full"`.
|
||||
### Caddy
|
||||
I usually use nginx, but I wanted to give Caddy a shot, and it has been a great experience. I installed Caddy using the [official instructions](https://caddyserver.com/docs/install).
|
||||
Here is the Caddyfile I made - you will need to change the domains names and the email. Email could be removed, but it is recommended so SSL certificate issues can contact you if there is a problem with your certificates.
|
||||
|
||||
`/etc/caddy/Caddyfile`
|
||||
```
|
||||
# Global options block
|
||||
{
|
||||
email you@example.com # <<<< change this
|
||||
on_demand_tls {
|
||||
ask http://localhost/check
|
||||
}
|
||||
}
|
||||
|
||||
omitted.webhooks.subdomain.tld { # <<<< change this
|
||||
reverse_proxy localhost:9000
|
||||
}
|
||||
|
||||
http://localhost {
|
||||
handle /check {
|
||||
root * /var/www
|
||||
@deny not file /{query.domain}/
|
||||
respond @deny 404
|
||||
}
|
||||
}
|
||||
|
||||
https:// {
|
||||
tls {
|
||||
on_demand
|
||||
}
|
||||
root /var/www
|
||||
rewrite /{host}{uri}
|
||||
# Block files that start with a .
|
||||
@forbidden {
|
||||
path /.*
|
||||
}
|
||||
respond @forbidden 404
|
||||
file_server
|
||||
}
|
||||
|
||||
# Refer to the Caddy docs for more information:
|
||||
# https://caddyserver.com/docs/caddyfile
|
||||
|
||||
# This config based on information at
|
||||
# https://caddy.community/t/on-demand-tls-with-dynamic-content-paths/18140
|
||||
# checked and corrected with `caddy validate`
|
||||
```
|
||||
I also took ownership of `/var/www` with `chown -R joshua:joshua /var/www` since the webhooks will run as my login account.
|
||||
### Webhook
|
||||
I altered the systemd service definition for `webhook` so I could organize the hook definitions into separate files. I also set `User=joshua` and `Group=joshua` so the commands run as my user instead of root.
|
||||
|
||||
`sudo mkdir /etc/webhook.conf.d/`
|
||||
|
||||
`/lib/systemd/system/webhook.service`
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Small server for creating HTTP endpoints (hooks)
|
||||
Documentation=https://github.com/adnanh/webhook/
|
||||
ConditionPathExists=/etc/webhook.conf
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/bin/webhook -nopanic -hooks /etc/webhook.conf.d/*.conf
|
||||
|
||||
User=joshua
|
||||
Group=joshua
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
If you are debugging your webhook output, consider adding `-debug` next to `-nopanic` for more useful logs.
|
||||
|
||||
After changing the service definition, reload systemd to run the updated service:
|
||||
``` bash
|
||||
sudo systemctl daemon-reload
|
||||
```
|
||||
Then you can remove the now-unused config file:
|
||||
``` bash
|
||||
sudo rm /etc/webhook.conf
|
||||
```
|
||||
Here are the three hook definitions:
|
||||
#### Create pages
|
||||
`/etc/webhook.conf.d/create-pages.conf`
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "create-pages",
|
||||
"execute-command": "/home/joshua/webhooks/create-pages.sh",
|
||||
"command-working-directory": "/var/www",
|
||||
"pass-arguments-to-command":
|
||||
[
|
||||
{
|
||||
"source": "payload",
|
||||
"name": "repository.name"
|
||||
},
|
||||
{
|
||||
"source": "payload",
|
||||
"name": "clone_url",
|
||||
}
|
||||
],
|
||||
"trigger-rule":
|
||||
{
|
||||
"and":
|
||||
[
|
||||
{
|
||||
"match":
|
||||
{
|
||||
"type": "payload-hmac-sha256",
|
||||
"secret": "(omitted)",
|
||||
"parameter":
|
||||
{
|
||||
"source": "header",
|
||||
"name": "X-Forgejo-Signature"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
#### Remove pages
|
||||
`/etc/webhook.conf.d/remove-pages.conf`
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "remove-pages",
|
||||
"execute-command": "/home/joshua/webhooks/remove-pages.sh",
|
||||
"command-working-directory": "/var/www",
|
||||
"pass-arguments-to-command":
|
||||
[
|
||||
{
|
||||
"source": "payload",
|
||||
"name": "repository.name"
|
||||
},
|
||||
],
|
||||
"trigger-rule":
|
||||
{
|
||||
"and":
|
||||
[
|
||||
{
|
||||
"match":
|
||||
{
|
||||
"type": "payload-hmac-sha256",
|
||||
"secret": "(omitted)",
|
||||
"parameter":
|
||||
{
|
||||
"source": "header",
|
||||
"name": "X-Forgejo-Signature"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
#### Update pages
|
||||
`/etc/webhook.conf.d/update-pages.conf`
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "update-pages",
|
||||
"execute-command": "/home/joshua/webhooks/update-pages.sh",
|
||||
"command-working-directory": "/var/www",
|
||||
"pass-arguments-to-command":
|
||||
[
|
||||
{
|
||||
"source": "payload",
|
||||
"name": "repository.name"
|
||||
},
|
||||
],
|
||||
"trigger-rule":
|
||||
{
|
||||
"and":
|
||||
[
|
||||
{
|
||||
"match":
|
||||
{
|
||||
"type": "payload-hmac-sha256",
|
||||
"secret": "(omitted)",
|
||||
"parameter":
|
||||
{
|
||||
"source": "header",
|
||||
"name": "X-Forgejo-Signature"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"match":
|
||||
{
|
||||
"type": "value",
|
||||
"value": "refs/heads/gh-pages",
|
||||
"parameter":
|
||||
{
|
||||
"source": "payload",
|
||||
"name": "ref"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
In my home directory I defined all three hook scripts:
|
||||
|
||||
`webhooks/create-pages.sh`
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# parameter 1 is repo name, parameter 2 is clone URL
|
||||
[[ "$1" == *"/"* ]] && exit 1; # no slashes in the name
|
||||
[[ "$1" == *".."* ]] && exit 1; # no .. in the name
|
||||
[[ "$1" == *"*"* ]] && exit 1; # no wildcards in the name
|
||||
[ -d "/var/www/$1" ] && exit 1; # the directory must not exist
|
||||
cd "/var/www";
|
||||
git clone -b gh-pages --single-branch "$2" "$1" || exit 1;
|
||||
```
|
||||
|
||||
`webhooks/remove-pages.sh`
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# parameter 1 is repo name
|
||||
[[ "$1" == *"/"* ]] && exit 1; # no slashes in the name
|
||||
[[ "$1" == *".."* ]] && exit 1; # no .. in the name
|
||||
[[ "$1" == *"*"* ]] && exit 1; # no wildcards in the name
|
||||
[ -d "/var/www/$1" ] && exit 1; # the directory must exist
|
||||
cd "/var/www";
|
||||
rm -rf "/var/www/$1";
|
||||
```
|
||||
`webhooks/update-pages.sh`
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# parameter 1 is repo name
|
||||
[[ "$1" == *"/"* ]] && exit 1; # no slashes in the name
|
||||
[[ "$1" == *".."* ]] && exit 1; # no .. in the name
|
||||
[[ "$1" == *"*"* ]] && exit 1; # no wildcards in the name
|
||||
[ -d "/var/www/$1" ] || exit 1; # the directory must exist
|
||||
cd "/var/www/$1";
|
||||
git fetch origin gh-pages;
|
||||
git reset --hard origin/gh-pages;
|
||||
exit;
|
||||
```
|
||||
### Forgejo
|
||||
Forgejo supports running webhooks conditionally triggered by certain conditions.
|
||||
Under my main user settings I set up each webhook:
|
||||
#### Create pages
|
||||
Target URL: https:// _your domain here_ /hooks/create-pages
|
||||
HTTP Method: `POST` (the default)
|
||||
POST content type: `application/json` (the default)
|
||||
Secret: _omitted, use your own_
|
||||
Trigger on: Custom Events > Create
|
||||
Branch filter: `gh-pages`
|
||||
#### Remove pages
|
||||
Target URL: https:// _your domain here_ /hooks/remove-pages
|
||||
HTTP Method: `POST` (the default)
|
||||
POST content type: `application/json` (the default)
|
||||
Secret: _omitted, use your own_
|
||||
Trigger on: Custom Events > Repository > Delete
|
||||
Branch filter: `gh-pages`
|
||||
#### Update pages
|
||||
Target URL: https:// _your domain here_ /hooks/update-pages
|
||||
HTTP Method: `POST` (the default)
|
||||
POST content type: `application/json` (the default)
|
||||
Secret: _omitted, use your own_
|
||||
Trigger on: Push events
|
||||
Branch filter: `gh-pages`
|
||||
|
||||
## Conclusion
|
||||
It works!
|
||||
This repo is in my Forgejo instance: https://git.apps.seigler.net/joshua/marklink.pages.seigler.net
|
||||
And its contents are visible here on my Caddy server: https://marklink.pages.seigler.net/
|
||||
|
||||
There is room to make the scripts a little smarter. They don't handle renaming very well right now, and a few times I had to log in and manually run my webhook scripts, like this:
|
||||
```bash
|
||||
~/webhooks/create-pages.sh marklink.pages.seigler.net "https://git.apps.seigler.net/joshua/marklink.pages.seigler.net.git"
|
||||
```
|
||||
The really important thing is that updates just require pushing to `gh-pages` which you can easily do with e.g. [gh-pages @ npm](https://www.npmjs.com/package/gh-pages).
|
||||
|
||||
I'm also putting off rolling my own CI server, but I imagine that's the next stage here. Stay tuned.
|
||||
Loading…
Add table
Add a link
Reference in a new issue