Forgejo

Publish static sites

It is possible to easily configure a Forgejo repository to be built and published on any unused subdomain of frog-collective.com. To to so, you must configure a web hook in the repository so that push events can trigger the host building and serving static web pages.

Configuration

You must have the administration rights on the repository you want to publish. To publish a repository, you must first configure a web hook on it.

If your repository is in an organization, go to the Settings page of your Organization, and check that Public is selected in the Visibilty section. Don't forget to click Update Settings if you change the visibility.

Go to the Settings page of the repository you want to publish.
Select the Repository tab.
Check that the checkbox ~~Visibility [ ]~~ Make the repository private is unchecked. If not, uncheck it and click Update ~~Settings~~Settings..
Now select the Webhooks tab.
Click Add Webhook and choose the Forgejo hook type.
Fill the form :
- Target URL : enter https://fsp.frog-collective.com (FSP stands for Forgejo Static Pages)
- HTTP Method: select POST
- Post content type: select application/json
- Secret: For now, you must ask the secret to someone who knows it. Write on the IT channel on Discord, or send a mail to admin@collectivit.org
- Trigger On: select push events
- Branch filter: you probably want to enter main here.
- Authorization header: Leave blank
Click Add webhook

Now that the web hook is configured, add a file at the root of your repository named .static-pages.yml with the following content :

site_name: frog-collective.com # The hostname where the website will be available
build_command: nox -r -s build # The command to run to build your pages
build_directory: build # The folder relative to the repository root where the pages are, once built

Add it, commit on the branch you entered in the Branch filter field when configuring the web hook, and push. After a while, your website should appear at the configured address.

Never leak the web hook secret : as the pages are built by running a custom command, having access to this secret means being able to run arbitrary code on the CollectivIT production servers. For the same reason, be cautious when you configure your build commands.

The environment in which the build is launched on the static pages server is limited. You can use bash, python and nox. Don't expect other software to be available, as it is subject to change without notice. If you have other build dependencies, nox is a good way to go to create virtual environments to install them, and nodeenv can be used to create nodejs virtualenvs if you need npm.

For now it is not possible to build different branches to different domains, but it could be easily added, fill a ticket on https://git.frog-collective.com/collectivit/collectivit/issues if you want that.

Troubleshooting

If your website doesn't go online in a reasonable amount of time after you pushed, first, check that the hook is sent and received :

Go to the Settings page of your repository
On the Webhook tab, click on the web hook you created (https://fsp.frog-collective.com)
At the bottom of the page, there is a Recent delivery panel, that should contains the last events sent by Forgejo.
- If there are no events, check that the Filter branch field is correctly filled.
- If you see some event that failed, click and them and inspect the Response tab : the Body section can contain useful information on what's going wrong (bad hook secret...).
- If the Body section contains {"status": "queued"} but nothing gets online, double check the command you configured in the build_command field of your .static-pages.yml and that it runs correctly on your machine. Check that the build_directory is also correct.
- If it's still not working, I'm sorry there is nothing to check the build log on the remote machine for now, so ping the #it channel on the Discord server, or send a mail to admin@collectivit.org for help.