Parasol Static Site ☂️ 🕸️

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

  • Category: Development
  • Status: 0, dev
  • Image: site-badger
  • Healthcheck: {{ .Healthcheck }}
  • Backups: No
  • Email: No
  • Tests: No
  • SSO: No

Quick start

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

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

  • Public Site & Public Repo
  • HTTP Basic Auth & Public Repo
  • Public Site & Private Repo
  • 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

HTTP Basic Auth

To enable a password protected site built from a public git repo, 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.

When you deploy:

  • /: the Hugo site is served
  • /deploy: the webhook is behind HTTP Basic Auth

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

Then, you need to remove the final newline of the file:

$ truncate -s -1 <ssh-private-key-file>

Due to a limitation in abra (can't insert files yet), you'll have to manually ingest the SSH private key file manually. If you are deploying a site that is an alternative domain or sub-domain from the server name, please read this troubleshooting note.

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

If that completes with no errors, run the following command:

$ abra app secret ls example.org

If successful, you should see true in the far right column.

+------------+---------+----------------------------+-------------------+
|    NAME    | VERSION |       GENERATED NAME       | CREATED ON SERVER |
+------------+---------+----------------------------+-------------------+
| deploy_key | v1      | example_org_deploy_key_v1  | true              |
+------------+---------+----------------------------+-------------------+

You now need to upload the Public SSH key to the Git repository settings as a Deploy Key at which 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 nicely.

$ abra app deploy example.org

HTTP Basic Auth & Private Repository

You need to edit the COMPOSE_FILE= line to include the following .yml files:

COMPOSE_FILE="compose.yml:compose.auth.yml:compose.private.yml"

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

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.
Description
Hugo static sites with webhook updates
Readme 139 KiB
Languages
Shell 100%