Parasol Static Site ☂️ 🕸️

A recipe for generating static websites with Hugo and a listener service which triggers git pulls and builds via webhookd

• Maintainer: @stevensting
• Category: Development
• Status: 3, stable
• Image: site-badger
• Healthcheck: yes
• Backups: not necessary
• Email: not necessary
• Tests: No
• SSO: not necessary

Quick start

• abra app new parasol-static-site --secrets
• abra app config <app-site-name>
• abra app deploy <app-site-name>

This will deploy a public website built from a Hugo site stored in a git repository. If you need various private modes, there are different deployment options supported:

• Public Git Repo
• Private Git Repo with deploy key
• /deploy endpoint protected with HTTP Basic Auth
• HTTP Basic Auth & Private Repo

Public Site & Public Repo

The default deployment is a fully public site and public git repository.

• /: the Hugo site is served
• /deploy: triggers webhookd to re-build the site, includes publicly viewable build logs. ⚠️ Be aware that misuse could lead to constant CPU usage on your server, as /deploy is not rate limited. This mode is not recommended

Use HTTP Basic Auth for /deploy endpoint

To enable a password protected /deploy endpoint, uncomment the following lines in your .env file:

COMPOSE_FILE="$COMPOSE_FILE:compose.auth.yml"
AUTH_ENABLED=1
AUTH_USERNAME=foobar
SECRET_AUTH_PASSWORD_VERSION=v1

Then run abra app secret generate -a <domain> command.

Use automatic deployment with your GIT instance

Depending on which git platform you use, adding the auth information might be a little different. This is how it works with Forgejo/Codeberg. Generate a bas64 coded token for the protected endpoint:

echo -n '<username>:<SECRET_AUTH_PASSWORD>' | base64

Create a webhook which triggers the endpoint /deploy on push events for your git branch and add the following to the field authentication header:

Basic <bas64-coded-token>

Us a Private Repository

If you enable the following lines in your .env file:

COMPOSE_FILE="$COMPOSE_FILE:compose.private.yml"
PRIVATE_ENABLED=1
SECRET_DEPLOY_KEY_VERSION=v1

Then you need to generate a SSH key:

$ ssh-keygen -a 100 -t ed25519 -C <domainname>

Then, insert the secret:

$ abra secret insert <domain> deploy_key v1 -f -t <path-to/ssh-private-key-file>

You now need to upload the Public SSH key to the Git repository settings as a Deploy Key at the forge website you use. This is usually located in some web UI flow like:

Repository -> Settings > Deploy keys

Easiest is to copy the URLs below and change the user/website-repo values to match your site:

https://github.com/user/website-repo/settings/keys
https://gitlab.com/user/website-repo/-/settings/repository#js-deploy-keys-settings
https://git.coopcloud.tech/user/website-repo/settings/keys
https://codeberg.org/user/website-repo/settings/keys

You can then deploy the abra recipe and the deploy key will be loaded before cloning the private repository and all should work nicely.

$ abra app deploy example.org

Usage

To trigger the deploy webhook with normal HTTP request

curl -v -XPOST https://example.org/deploy

To trigger the deploy webhook with HTTP Auth enabled, add the header with:

curl -v XPOST -H "Authorization: Basic <insert password token>" https://hook.com/deploy

Assuming all is setup correctly, you should see the build triggered when viewing abra app log example.org log output.

Troubleshooting

This is a WIP, there are likely dragons and foot cannons. Ye be warned 🐉 🏴‍☠️ 😬

Site not generating?

You can manually trigger the site build yourself:

abra app run <domain> badger sh
sh /root/scripts/deploy.sh

SSH keys not working?

You can get in and inspect the SSH keys via the following:

abra app run <domain> badger sh
ls /root/.ssh

HTTP Basic auth not working?

Best to check the generated password file:

abra app run <domain> badger sh
cat /etc/nginx/.htpasswd

Alternative Domains & Sub-Domains

If you are deploying a private repository where a alternative domain (alternative.com) or a sub-domain (sub.example.org) from that of the server example.org you need to craft a special DOCKER_CONTEXT value. If your apps are named:

• alternative.com
• sub.example.org

Then the respective commands would be:

$ DOCKER_CONTEXT=example.org docker secret create alternative_com_deploy_key_v1 /path/to/ssh-private-key
$ DOCKER_CONTEXT=example.org docker secret create sub_example_org_deploy_key_v1 /path/to/ssh-private-key

For more details documentation, see the Coop-Cloud Docs

• docs.coopcloud.tech

License

The following starter was made by @adz for offline.place with the following license:

UNIVERSAL PUBLIC DOMAIN LICENSE

This software and everything else in the universe is in the public domain. Ideas are not property.