Today we are open-sourcing Impuls, a small container image we built to scratch an itch we kept feeling: getting a website (often documentation for a client’s project) from git push to served page, without re-inventing the deployment plumbing every single time.

Quality code, quality documentation

At eXact lab we hold a quiet conviction: code is only as good as the documentation that accompanies it. Clever software that nobody canconfigure without reading the source is not finished work, it is a liability with good intentions.

Introducing Impuls

Most forges sport some kind of “pages” feature, that sources its content from a git repository and automagically remains in sync with it. But what about client projects or internal documentation, which should not be generally available or is downright a trade secret?

Static site generators are wonderful. You write your project documentation using Markdown, Restructured Text and the like, build it, and out comes a fast, dependable website. The awkward part is everything that happens next: how do
you serve the artifact your trustworthy generator created? Where does the build run? How does it know the repository changed, when all you have is a bare repository in a client’s server?

Impuls collapses all of that into a single container. It serves your site on port 80 and a webhook on 9000 to receive build triggers. A reverse proxy, such as Traefik, can route each independently, so the webhook stays public while the
site hides behind a VPN-only entrypoint. On a valid, HMAC-signed request it pulls your repository, runs the build command, and starts serving the output.

That is the whole story.

Two variants ship ready to go, impuls-hugo and impuls-zensical, with Hugo and Zensical pre-installed, respectively. The only thing you genuinely have to provide is a repository URL and a webhook secret.

Problem solved

Imagine a repository on private infrastructure. All there is to it is to tell Impuls how to access the repository and to share a secret between the two.

In the case of projects hosted on forges, it’s just a matter of configuring a signed webhook to Impuls. In the forgeless case, a simple post-receive hook can do the same.

There is ample discretion as to how to deploy Impuls, since the triggering endpoint is served on a different port with respect to the actual site. Use your favourite reverse proxy to publish either or both in any configuration, from the most open to the most restrictive.

Try it

Impuls is MIT-licensed and available now on Codeberg. If you maintain a documentation site or any statically generated page and you are tired of bespoke deployment glue, try it out and, if you feel like it, let us know what you think about it. We are open-sourcing it precisely because we think the answer to “how do I serve this site” should be boring, shared, and well documented, and we would rather maintain one good answer together than many private ones alone.

Quick links

• Hugo: https://gohugo.io/
• Impuls on Codeberg: https://codeberg.org/eXact-lab/impuls
• Zensical: https://zensical.org/docs/get-started/