# Parasol Static Site :open_umbrella: :spider_web: [![Build Status](https://build.coopcloud.tech/api/badges/coop-cloud/parasol-static-site/status.svg)](https://build.coopcloud.tech/coop-cloud/parasol-static-site) A recipe for generating static websites with [Hugo](https://gohugo.io) and a listener service which triggers git pulls and builds via [webhookd](https://github.com/ncarlier/webhookd) * **Maintainer**: [@stevensting](https://git.coopcloud.tech/stevensting) * **Category**: Development * **Status**: 3, stable * **Image**: [site-badger](https://git.coopcloud.tech/toolshed/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 ` * `abra app deploy ` 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 ':' | 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 ``` ### 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 ``` Then, insert the private key as a secret: ``` $ abra secret insert deploy_key v1 -f -t ``` 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 ```bash curl -v -XPOST https://example.org/deploy ``` To trigger the deploy webhook with HTTP Auth enabled, add the header with: ```bash curl -v XPOST -H "Authorization: Basic " 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 :dragon: :pirate_flag: :grimacing: #### Site not generating? You can manually trigger the site build yourself: ``` abra app run 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 badger sh ls /root/.ssh ``` #### HTTP Basic auth not working? Best to check the generated password file: ``` abra app run 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`](https://docs.coopcloud.tech) ## License The following starter was made by [@adz](https://adz.garden) for [offline.place](https://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. ```