Merge remote-tracking branch 'origin/main' into custom-deploy

.env.sample

@@ -1,19 +1,20 @@
 TYPE=parasol-static-site
 
-DOMAIN=parasol.example.com
+DOMAIN=parasol-static-site.example.com
 LETS_ENCRYPT_ENV=production
+COMPOSE_FILE="compose.yml"
 
 # **NOTE** Please change this value to your repo
-HUGO_GIT_URL=git@codeberg.org:offline/future.git
+HUGO_GIT_URL=git@codeberg.org:eotl/example-repo.git
 
-# HTTP basic auth protected deploy endpoint
+# HTTP Basic Auth protected /deploy endpoint
-#COMPOSE_FILE="compose.yml:compose.auth.yml"
+#COMPOSE_FILE="$COMPOSE_FILE:compose.auth.yml"
 #AUTH_ENABLED=1
 #AUTH_USERNAME=foobar
 #SECRET_AUTH_PASSWORD_VERSION=v1
 
 # Private repository deployment
-#COMPOSE_FILE="compose.yml:compose.private.yml"
+#COMPOSE_FILE="$COMPOSE_FILE:compose.private.yml"
 #PRIVATE_ENABLED=1
 #SECRET_DEPLOY_KEY_VERSION=v1
 

README.md

@@ -1,5 +1,4 @@
-Parasol Static Site
+# Parasol Static Site :open_umbrella: :spider_web:
-====================
 
 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)
 
@@ -18,48 +17,49 @@ A recipe for generating static websites with [Hugo](https://gohugo.io) and a lis
 * `abra app config <app-site-name>`
 * `abra app deploy <app-site-name>`
 
-For more, see [`docs.coopcloud.tech`](https://docs.coopcloud.tech).
+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:
 
-## Modes
+- Public Site & Public Repo
+- HTTP Basic Auth & Public Repo
+- Public Site & Private Repo
+- HTTP Basic Auth & Private Repo
 
-There are three different types of deployments currently supported:
+### Public Site & Public Repo
 
-- Public Site & Repo
+The default deployment is a **fully public** site and **public git repository.**
-- Public Site & Private Repo 
-- Private Site & Repo
-
-### Public
-
-The default deployment is **fully public**:
 
 * `/`: the Hugo site is served
-* `/deploy`: triggers `webhookd` to re-build the site, **includes publicly viewable logs**
+* `/deploy`: triggers `webhookd` to re-build the site, **includes publicly viewable build logs**
 
 
 ### HTTP Basic Auth
 
-If you enable this in your `.env` file:
+To enable a password protected site built from a public git repo, uncomment the
+following lines in your `.env` file:
 
 ```
-COMPOSE_FILE="compose.yml:compose.auth.yml"
+COMPOSE_FILE="$COMPOSE_FILE:compose.auth.yml"
 AUTH_ENABLED=1
 AUTH_USERNAME=foobar
 SECRET_AUTH_PASSWORD_VERSION=v1
 ```
 
-Then you can run `abra app secret generate -a <domain>`.
+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
+* `/deploy`: the webhook is behind HTTP Basic Auth
+
 
 ### Private Repository
 
-If you enable this in your `.env` file:
+If you enable the following lines in your `.env` file:
 
 ```
-COMPOSE_FILE="compose.yml:compose.private.yml"
+COMPOSE_FILE="$COMPOSE_FILE:compose.private.yml"
 PRIVATE_ENABLED=1
 SECRET_DEPLOY_KEY_VERSION=v1
 ```
@@ -76,18 +76,22 @@ 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](https://git.coopcloud.tech/coop-cloud/organising/issues/586)), you'll have to manually ingest the privater key file with this command:
+Due to a limitation in `abra` ([can't insert files yet](https://git.coopcloud.tech/coop-cloud/organising/issues/586)), 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](#alternative-domainssub-domains).
 
 ```
 $ DOCKER_CONTEXT=example.org docker secret create example_org_deploy_key_v1 /path/to/ssh-private-key
 ```
 
-Assuming that completes with no errors, run the following command to confirm the
+If that completes with no errors, run the following command:
-key was written to the server and look for `true` in the far right column:
 
 ```
 $ abra app secret ls example.org
+```
 
+If successful, you should see `true` in the far right column.
+
+```
 +------------+---------+----------------------------+-------------------+
 |    NAME    | VERSION |       GENERATED NAME       | CREATED ON SERVER |
 +------------+---------+----------------------------+-------------------+
@@ -95,28 +99,63 @@ $ abra app secret ls example.org
 +------------+---------+----------------------------+-------------------+
 ```
 
-Then, you need to upload the public SSH key part to the Git repository settings
+You now need to upload the Public SSH key to the Git repository settings
-as a "Deploy key". In *Gitea*, that is located in: 
+as a `Deploy Key` at which forge website you use. This is usually 
+located in some web UI flow like:
 
 ```
-Repository Settings > Deploy keys
+Repository -> Settings > Deploy keys
 ```
 
-You can then deploy and the deploy key will be loaded before cloning the private
+Easiest is to copy the URLs below and change the `user/website-repo` values to
-repository and all should nicely.
+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
 
-Combine them with the `COMPOSE_FILE` technique:
+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
+
+```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 <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.
+This is a WIP, there are likely dragons and foot cannons. Ye be warned :dragon: :pirate_flag: :grimacing:
+
 
 #### Site not generating?
 
@@ -145,6 +184,28 @@ 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`](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:

abra.sh

@@ -3,4 +3,4 @@ export BADGER_ENTRYPOINT_VERSION=v1
 export DEFAULT_CONF_VERSION=v1
 export SSH_CONF_VERSION=v1
 export SSH_DEPLOY_KEY_VERSION=v1
-export WEBHOOKD_SCRIPT_VERSION=v2
+export WEBHOOKD_SCRIPT_VERSION=v3

compose.yml

@@ -26,6 +26,7 @@ services:
         - "traefik.http.routers.${STACK_NAME}.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
         - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
+        - "coop-cloud.${STACK_NAME}.version=v0.2.0+1.25.3-alpine"
 
   badger:
     image: codeberg.org/eotl/site-badger:0.1.0
@@ -33,6 +34,7 @@ services:
       - CUSTOM_DEPLOY_ENABLED
       - CUSTOM_DEPLOY_SCRIPT
       - HUGO_GIT_URL
+      - HUGO_GIT_BRANCH
       - HUGO_PUBLIC_DIR=/usr/share/nginx/website
       - HUGO_WORKING_DIR=/root/website
       - PRIVATE_ENABLED

deploy.sh.tmpl

@@ -23,6 +23,12 @@ echo "◆ Pull latest version from .git repository"
 git fetch --all
 git reset --hard origin/main
 
+if [ ! -z "$HUGO_GIT_BRANCH" ]; then
+  echo "Checkout $HUGO_GIT_BRANCH"
+  git reset --hard origin/$HUGO_GIT_BRANCH
+  git checkout origin/$HUGO_GIT_BRANCH
+fi
+
 if [ "$CUSTOM_DEPLOY_ENABLED" == "1" ]; then
   echo "◆ Executing custom deploy script: $HUGO_WORKING_DIR/$CUSTOM_DEPLOY_SCRIPT"
   bash $HUGO_WORKING_DIR/$CUSTOM_DEPLOY_SCRIPT