Updates
This commit is contained in:
Joshua Seigler
parent
cac775b076
commit
6d54ca2954
11 changed files with 1043 additions and 11 deletions
544
posts/my-very-own-github-pages/index.html
Normal file
544
posts/my-very-own-github-pages/index.html
Normal file
|
|
@ -0,0 +1,544 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta
|
||||
name="viewport"
|
||||
content="width=device-width, initial-scale=1.0, viewport-fit=cover"
|
||||
/>
|
||||
<link rel="stylesheet" href="/site.css?v=b0813e810319" />
|
||||
<link rel="me" href="https://github.com/seigler" />
|
||||
<link
|
||||
rel="webmention"
|
||||
href="https://webmention.io/joshua.seigler.net/webmention"
|
||||
/>
|
||||
<title>My Very Own GitHub Pages - joshua.seigler.net</title>
|
||||
<meta
|
||||
name="description"
|
||||
content="How to self-host Forgejo and automatically serve your web build branches with SSL"
|
||||
/>
|
||||
<meta property="og:title" content="My Very Own GitHub Pages" />
|
||||
<meta property="og:type" content="" />
|
||||
<meta
|
||||
property="og:url"
|
||||
content="https://joshua.seigler.net/posts/my-very-own-github-pages/"
|
||||
/>
|
||||
<meta name="twitter:title" content="My Very Own GitHub Pages" />
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="How to self-host Forgejo and automatically serve your web build branches with SSL"
|
||||
/>
|
||||
|
||||
<meta name="twitter:card" content="summary" />
|
||||
<meta name="generator" content="Eleventy v3.1.0" />
|
||||
<script
|
||||
defer
|
||||
src="https://stats.apps.seigler.net/script.js"
|
||||
data-website-id="ccb4bd94-2a71-47fe-8eea-d85bf75b7f6d"
|
||||
></script>
|
||||
<script defer src="/scripts/effects.js?v=cd61c39d895d"></script>
|
||||
</head>
|
||||
<body data-font="english" data-path="/posts/my-very-own-github-pages/">
|
||||
<header>
|
||||
<nav>
|
||||
<div class="nav-row">
|
||||
<div class="nav-home"><a href="/">joshua.seigler.net</a></div>
|
||||
<div class="nav-settings">
|
||||
<div class="nav-toggles">
|
||||
<label class="nav-toggle-button" title="Light mode"
|
||||
>☀️<input type="radio" name="theme" value="light"
|
||||
/></label>
|
||||
<label class="nav-toggle-button" title="Automatic"
|
||||
>🔄<input type="radio" name="theme" value="auto"
|
||||
/></label>
|
||||
<label class="nav-toggle-button" title="Dark mode"
|
||||
>🌒<input type="radio" name="theme" value="dark"
|
||||
/></label>
|
||||
</div>
|
||||
<div class="nav-toggles">
|
||||
<label class="nav-toggle-button" data-language="english"
|
||||
>English<input type="radio" name="language" value="english"
|
||||
/></label>
|
||||
<label class="nav-toggle-button" data-language="aurebesh"
|
||||
>Aurebesh<input type="radio" name="language" value="aurebesh"
|
||||
/></label>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="nav-categories">
|
||||
<a class="nav-active" href="/posts/">/posts</a>
|
||||
<a class="" href="/about/">/about</a>
|
||||
<a class="" href="/now/">/now</a>
|
||||
<a class="" href="/uses/">/uses</a>
|
||||
<a class="" href="/recipes/">/recipes</a>
|
||||
<a class="" href="/music/">/music</a>
|
||||
<a class="" href="/books/">/books</a>
|
||||
<a class="" href="/search/">/search</a>
|
||||
</div>
|
||||
</nav>
|
||||
<h1>My Very Own GitHub Pages</h1>
|
||||
<div class="header-meta">
|
||||
<author>Joshua Seigler</author><date>June 15, 2025</date>
|
||||
</div>
|
||||
</header>
|
||||
<main data-pagefind-body>
|
||||
<p>
|
||||
I recently started self-hosting
|
||||
<a href="https://forgejo.org/" target="_blank" rel="noopener">Forgejo</a
|
||||
>, 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
|
||||
<a
|
||||
href="https://github.com/adnanh/webhook"
|
||||
target="_blank"
|
||||
rel="noopener"
|
||||
>webhook</a
|
||||
>
|
||||
and
|
||||
<a href="https://caddyserver.com/" target="_blank" rel="noopener"
|
||||
>Caddy</a
|
||||
>. I’m very happy how it turned out.
|
||||
</p>
|
||||
<h2 id="the-result" tabindex="-1">
|
||||
<a class="header-anchor" href="#the-result" aria-hidden="true"></a> The
|
||||
result
|
||||
</h2>
|
||||
<p>
|
||||
When I push a <code>gh-pages</code> branch to any public repository on
|
||||
my Forgejo instance, the name of the repo is used as a domain name (e.g.
|
||||
<a
|
||||
href="https://marklink.pages.seigler.net/"
|
||||
target="_blank"
|
||||
rel="noopener"
|
||||
>marklink.pages.seigler.net</a
|
||||
>) 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.
|
||||
</p>
|
||||
<h2 id="how-to-do-it" tabindex="-1">
|
||||
<a class="header-anchor" href="#how-to-do-it" aria-hidden="true"></a>
|
||||
How to do it
|
||||
</h2>
|
||||
<h3 id="debian-server-preparation" tabindex="-1">
|
||||
<a
|
||||
class="header-anchor"
|
||||
href="#debian-server-preparation"
|
||||
aria-hidden="true"
|
||||
></a>
|
||||
Debian server preparation
|
||||
</h3>
|
||||
<p>
|
||||
In case you don’t have a basic server setup routine yet, this is a good
|
||||
start:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Change the default root password</li>
|
||||
<li>
|
||||
Create a new user, add it to the sudo group. In my examples below the
|
||||
user is <code>joshua</code>.
|
||||
</li>
|
||||
<li>
|
||||
Use <code>ssh-copy-id</code> to install your ssl pubkey for easier
|
||||
login
|
||||
</li>
|
||||
<li>Disable/lock root’s password</li>
|
||||
<li>
|
||||
Disable root login over ssh and change the SSL port number. Pick a new
|
||||
port lower than 1024.
|
||||
</li>
|
||||
<li>
|
||||
Edit your local <code>~/.ssh/config</code> so you don’t have to
|
||||
specify the port number every time you connect.
|
||||
</li>
|
||||
<li>
|
||||
On the server, install and enable <code>ufw</code> and
|
||||
<code>fail2ban</code>. In addition to allowing your custom SSL port,
|
||||
be sure to enable ports 80 and 443 with
|
||||
<code>sudo ufw allow "WWW Full"</code>.
|
||||
</li>
|
||||
</ul>
|
||||
<h3 id="caddy" tabindex="-1">
|
||||
<a class="header-anchor" href="#caddy" aria-hidden="true"></a> Caddy
|
||||
</h3>
|
||||
<p>
|
||||
I usually use nginx, but I wanted to give Caddy a shot, and it has been
|
||||
a great experience. I installed Caddy using the
|
||||
<a
|
||||
href="https://caddyserver.com/docs/install"
|
||||
target="_blank"
|
||||
rel="noopener"
|
||||
>official instructions</a
|
||||
>.<br />
|
||||
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.
|
||||
</p>
|
||||
<p><code>/etc/caddy/Caddyfile</code></p>
|
||||
<pre><code># 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`
|
||||
</code></pre>
|
||||
<p>
|
||||
I also took ownership of <code>/var/www</code> with
|
||||
<code>chown -R joshua:joshua /var/www</code> since the webhooks will run
|
||||
as my login account.
|
||||
</p>
|
||||
<h3 id="webhook" tabindex="-1">
|
||||
<a class="header-anchor" href="#webhook" aria-hidden="true"></a> Webhook
|
||||
</h3>
|
||||
<p>
|
||||
I altered the systemd service definition for <code>webhook</code> so I
|
||||
could organize the hook definitions into separate files. I also set
|
||||
<code>User=joshua</code> and <code>Group=joshua</code> so the commands
|
||||
run as my user instead of root.
|
||||
</p>
|
||||
<p><code>sudo mkdir /etc/webhook.conf.d/</code></p>
|
||||
<p><code>/lib/systemd/system/webhook.service</code></p>
|
||||
<pre><code class="language-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
|
||||
</code></pre>
|
||||
<p>
|
||||
If you are debugging your webhook output, consider adding
|
||||
<code>-debug</code> next to <code>-nopanic</code> for more useful logs.
|
||||
</p>
|
||||
<p>
|
||||
After changing the service definition, reload systemd to run the updated
|
||||
service:
|
||||
</p>
|
||||
<pre><code class="language-bash">sudo systemctl daemon-reload
|
||||
</code></pre>
|
||||
<p>Then you can remove the now-unused config file:</p>
|
||||
<pre><code class="language-bash">sudo rm /etc/webhook.conf
|
||||
</code></pre>
|
||||
<p>Here are the three hook definitions:</p>
|
||||
<h4 id="create-pages" tabindex="-1">
|
||||
<a class="header-anchor" href="#create-pages" aria-hidden="true"></a>
|
||||
Create pages
|
||||
</h4>
|
||||
<p><code>/etc/webhook.conf.d/create-pages.conf</code></p>
|
||||
<pre><code class="language-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"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
</code></pre>
|
||||
<h4 id="remove-pages" tabindex="-1">
|
||||
<a class="header-anchor" href="#remove-pages" aria-hidden="true"></a>
|
||||
Remove pages
|
||||
</h4>
|
||||
<p><code>/etc/webhook.conf.d/remove-pages.conf</code></p>
|
||||
<pre><code class="language-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"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
</code></pre>
|
||||
<h4 id="update-pages" tabindex="-1">
|
||||
<a class="header-anchor" href="#update-pages" aria-hidden="true"></a>
|
||||
Update pages
|
||||
</h4>
|
||||
<p><code>/etc/webhook.conf.d/update-pages.conf</code></p>
|
||||
<pre><code class="language-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"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
</code></pre>
|
||||
<p>In my home directory I defined all three hook scripts:</p>
|
||||
<p><code>webhooks/create-pages.sh</code></p>
|
||||
<pre><code class="language-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;
|
||||
</code></pre>
|
||||
<p><code>webhooks/remove-pages.sh</code></p>
|
||||
<pre><code class="language-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";
|
||||
</code></pre>
|
||||
<p><code>webhooks/update-pages.sh</code></p>
|
||||
<pre><code class="language-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;
|
||||
</code></pre>
|
||||
<h3 id="forgejo" tabindex="-1">
|
||||
<a class="header-anchor" href="#forgejo" aria-hidden="true"></a> Forgejo
|
||||
</h3>
|
||||
<p>
|
||||
Forgejo supports running webhooks conditionally triggered by certain
|
||||
conditions.<br />
|
||||
Under my main user settings I set up each webhook:
|
||||
</p>
|
||||
<h4 id="create-pages-1" tabindex="-1">
|
||||
<a class="header-anchor" href="#create-pages-1" aria-hidden="true"></a>
|
||||
Create pages
|
||||
</h4>
|
||||
<p>
|
||||
Target URL: https:// <em>your domain here</em> /hooks/create-pages<br />
|
||||
HTTP Method: <code>POST</code> (the default)<br />
|
||||
POST content type: <code>application/json</code> (the default)<br />
|
||||
Secret: <em>omitted, use your own</em><br />
|
||||
Trigger on: Custom Events > Create<br />
|
||||
Branch filter: <code>gh-pages</code>
|
||||
</p>
|
||||
<h4 id="remove-pages-1" tabindex="-1">
|
||||
<a class="header-anchor" href="#remove-pages-1" aria-hidden="true"></a>
|
||||
Remove pages
|
||||
</h4>
|
||||
<p>
|
||||
Target URL: https:// <em>your domain here</em> /hooks/remove-pages<br />
|
||||
HTTP Method: <code>POST</code> (the default)<br />
|
||||
POST content type: <code>application/json</code> (the default)<br />
|
||||
Secret: <em>omitted, use your own</em><br />
|
||||
Trigger on: Custom Events > Repository > Delete<br />
|
||||
Branch filter: <code>gh-pages</code>
|
||||
</p>
|
||||
<h4 id="update-pages-1" tabindex="-1">
|
||||
<a class="header-anchor" href="#update-pages-1" aria-hidden="true"></a>
|
||||
Update pages
|
||||
</h4>
|
||||
<p>
|
||||
Target URL: https:// <em>your domain here</em> /hooks/update-pages<br />
|
||||
HTTP Method: <code>POST</code> (the default)<br />
|
||||
POST content type: <code>application/json</code> (the default)<br />
|
||||
Secret: <em>omitted, use your own</em><br />
|
||||
Trigger on: Push events<br />
|
||||
Branch filter: <code>gh-pages</code>
|
||||
</p>
|
||||
<h2 id="conclusion" tabindex="-1">
|
||||
<a class="header-anchor" href="#conclusion" aria-hidden="true"></a>
|
||||
Conclusion
|
||||
</h2>
|
||||
<p>
|
||||
It works!<br />
|
||||
This repo is in my Forgejo instance:
|
||||
<a
|
||||
href="https://git.apps.seigler.net/joshua/marklink.pages.seigler.net"
|
||||
target="_blank"
|
||||
rel="noopener"
|
||||
>https://git.apps.seigler.net/joshua/marklink.pages.seigler.net</a
|
||||
><br />
|
||||
And its contents are visible here on my Caddy server:
|
||||
<a
|
||||
href="https://marklink.pages.seigler.net/"
|
||||
target="_blank"
|
||||
rel="noopener"
|
||||
>https://marklink.pages.seigler.net/</a
|
||||
>
|
||||
</p>
|
||||
<p>
|
||||
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:
|
||||
</p>
|
||||
<pre><code class="language-bash">~/webhooks/create-pages.sh marklink.pages.seigler.net "https://git.apps.seigler.net/joshua/marklink.pages.seigler.net.git"
|
||||
</code></pre>
|
||||
<p>
|
||||
The really important thing is that updates just require pushing to
|
||||
<code>gh-pages</code> which you can easily do with e.g.
|
||||
<a
|
||||
href="https://www.npmjs.com/package/gh-pages"
|
||||
target="_blank"
|
||||
rel="noopener"
|
||||
>gh-pages @ npm</a
|
||||
>.
|
||||
</p>
|
||||
<p>
|
||||
I’m also putting off rolling my own CI server, but I imagine that’s the
|
||||
next stage here. Stay tuned.
|
||||
</p>
|
||||
|
||||
<script
|
||||
data-isso="//comments.apps.seigler.net/"
|
||||
src="//comments.apps.seigler.net/js/embed.min.js"
|
||||
></script>
|
||||
|
||||
<section id="isso-thread" data-title="">
|
||||
<noscript>Javascript needs to be activated to view comments.</noscript>
|
||||
</section>
|
||||
</main>
|
||||
<footer>
|
||||
<section>
|
||||
© Joshua Seigler 2025. -
|
||||
<a rel="me" href="mailto:joshua@seigler.net?subject=Hello">Contact</a>
|
||||
-
|
||||
<a href="/feed.xml">RSS</a>
|
||||
-
|
||||
<a href="/unoffice-hours/">Unoffice Hours</a>
|
||||
</section>
|
||||
<section>
|
||||
Webrings:
|
||||
<strong>Unoffice Hours</strong>
|
||||
<a href="https://unofficehours.com/prev.html" rel="noopener">Prev</a>
|
||||
<a href="https://unofficehours.com/next.html" rel="noopener">Next</a>
|
||||
<a href="https://unofficehours.com/random.html" rel="noopener"
|
||||
>Random</a
|
||||
>
|
||||
<a href="https://unofficehours.com" rel="noopener">List</a>
|
||||
</section>
|
||||
</footer>
|
||||
<div id="effects"></div>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Add table
Add a link
Reference in a new issue