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 served from a 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 and factually DDoS the site, as /deploy is not rate limited. This mode is not recommended. Add basic auth to all /deploy endpoints!

Additional staging deployment

Additionally to the deployment of the regular site, a staging deployment can be activated. This will be served at the staging subdomain. To activate it set the branch from which the site shall be built with HUGO_GIT_BRANCH_STAGING and activate the compose file and the EXTRA_DOMAINS.

HTTP Basic Auth Protection

To enable a password protection for your site, uncomment the lines after # HTTP Basic Auth protection in your .env file: 4 different endpoints can be protected: the /deploy endpoints of the default site and the staging site. Also the default site and the staging site can be protected as a whole. Set the corresponding env vars as needed.

Then run abra app secret generate example.org auth_password v1 command. Note the generated password to be able to access the protected endpoints later. This password is used for all 4 possible endpoints. Also set a user name in AUTH_USERNAME.

In case you protect one or both deploy endpoints with basic auth, you need to give the username password combination to your git service.

Automatic deployment with protected endpoints 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. Do this also for the deploy endpoint of the staging site if you actevated it. Generate a base64 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>

Use a Private Repository

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 private key as a 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.