witryna 0.1.0 — initial releasev0.1.0

Minimalist Git-based static site deployment orchestrator.
Webhook-triggered builds in Podman/Docker containers with atomic
symlink publishing, SIGHUP hot-reload, and zero-downtime deploys.

See README.md for usage, CHANGELOG.md for details.

1 files changed, 490 insertions, 0 deletions

diff --git a/man/witryna.toml.5 b/man/witryna.toml.5
new file mode 100644
index 0000000..29c0331
--- /dev/null
+++ b/man/witryna.toml.5
@@ -0,0 +1,490 @@
+.TH WITRYNA.TOML 5 "2026-02-10" "witryna 0.1.0" "Witryna Configuration"
+.SH NAME
+witryna.toml \- configuration file for \fBwitryna\fR(1)
+.SH DESCRIPTION
+\fBwitryna.toml\fR is a TOML file that configures the \fBwitryna\fR static site
+deployment orchestrator.
+It defines the HTTP listen address, container runtime, directory layout,
+logging, rate limiting, and zero or more site definitions with optional build
+overrides, polling intervals, cache volumes, and post\-deploy hooks.
+.PP
+The file is read at startup and can be reloaded at runtime by sending
+\fBSIGHUP\fR to the process (see \fBHOT RELOAD\fR below).
+.SH GLOBAL OPTIONS
+.TP
+\fBlisten_address\fR = "\fIhost:port\fR" (required)
+Socket address the HTTP server binds to.
+Must be a valid \fIip:port\fR pair (e.g., "127.0.0.1:8080").
+.TP
+\fBcontainer_runtime\fR = "\fIname\fR" (required)
+Container runtime executable used to run build commands.
+Typically "podman" or "docker".
+Must not be empty or whitespace\-only.
+.TP
+\fBbase_dir\fR = "\fI/path\fR" (required)
+Root directory for clones, builds, and cache.
+Default layout:
+.RS
+.nf
+<base_dir>/clones/<site>/
+<base_dir>/builds/<site>/<timestamp>/
+<base_dir>/builds/<site>/current -> <timestamp>
+<base_dir>/cache/<site>/
+.fi
+.RE
+.TP
+\fBlog_dir\fR = "\fI/path\fR" (optional, default: "/var/log/witryna")
+Directory for per\-build log files.
+Layout: \fI<log_dir>/<site>/<timestamp>.log\fR
+.TP
+\fBlog_level\fR = "\fIlevel\fR" (required)
+Tracing verbosity.
+Valid values: "trace", "debug", "info", "warn", "error" (case\-insensitive).
+Can be overridden at runtime with the \fBRUST_LOG\fR environment variable.
+.TP
+\fBrate_limit_per_minute\fR = \fIn\fR (optional, default: 10)
+Maximum webhook requests per token per minute.
+Exceeding this limit returns HTTP 429.
+.PP
+\fBNote:\fR The server enforces a hard 1\ MB request body size limit.
+This is not configurable and applies to all endpoints.
+.TP
+\fBmax_builds_to_keep\fR = \fIn\fR (optional, default: 5)
+Number of timestamped build directories to retain per site.
+Older builds and their corresponding log files are removed after each
+successful publish.
+Set to 0 to disable cleanup (keep all builds).
+.TP
+\fBgit_timeout\fR = "\fIduration\fR" (optional, default: "1m")
+Maximum time allowed for each git operation (clone, fetch, reset, submodule update).
+Accepts a \fBhumantime\fR duration string (e.g., "30s", "2m", "5m").
+.RS
+Minimum is 5 seconds, maximum is 1 hour.
+Applies globally to all sites.
+Repositories with many or large submodules may need a longer timeout (e.g., "5m").
+.RE
+.SH SITE DEFINITIONS
+Sites are defined as TOML array\-of\-tables entries under \fB[[sites]]\fR.
+Each site represents a Git repository that witryna can build and publish.
+Site names must be unique.
+The list may be empty (\fBsites = []\fR); witryna will start but serve
+only the health\-check endpoint.
+.TP
+\fBname\fR = "\fIsite\-name\fR" (required)
+Unique identifier for the site.
+Used in the webhook URL path (\fIPOST /<name>\fR) and directory names.
+.RS
+Validation rules:
+.IP \(bu 2
+Alphanumeric characters, hyphens, and underscores only.
+.IP \(bu 2
+Cannot start or end with a hyphen or underscore.
+.IP \(bu 2
+Cannot contain consecutive hyphens or consecutive underscores.
+.IP \(bu 2
+No path traversal characters (\fI..\fR, \fI/\fR, \fI\\\fR).
+.RE
+.TP
+\fBrepo_url\fR = "\fIurl\fR" (required)
+Git repository URL to clone.
+Any URL that \fBgit clone\fR accepts (HTTPS, SSH, local path).
+.TP
+\fBbranch\fR = "\fIref\fR" (required)
+Git branch to track.
+This branch is checked out after clone and fetched on each build trigger.
+.TP
+\fBwebhook_token\fR = "\fItoken\fR" (optional)
+Bearer token for webhook endpoint authentication.
+If omitted or set to an empty string, webhook authentication is disabled for
+this site \(em all POST requests to the site endpoint will be accepted without
+token validation.
+Use this when the endpoint is protected by other means (reverse proxy, VPN,
+firewall).
+A warning is logged at startup for sites without authentication.
+.PP
+When set, the token is validated using constant\-time comparison to prevent
+timing attacks.
+Sent as: \fIAuthorization: Bearer <token>\fR.
+.RS
+The token can be provided in three ways:
+.IP \(bu 2
+\fBLiteral value:\fR \fBwebhook_token = "my\-secret"\fR
+.IP \(bu 2
+\fBEnvironment variable:\fR \fBwebhook_token = "${VAR_NAME}"\fR \- resolved from
+the process environment at config load time.
+The variable name must consist of ASCII uppercase letters, digits, and underscores,
+and must start with a letter or underscore.
+Only full\-value substitution is supported; partial interpolation
+(e.g., "prefix\-${VAR}") is treated as a literal token.
+.IP \(bu 2
+\fBFile:\fR Use \fBwebhook_token_file\fR (see below).
+.PP
+The \fB${VAR}\fR syntax and \fBwebhook_token_file\fR are mutually exclusive.
+If the referenced environment variable is not set or the file cannot be read,
+config loading fails with an error.
+.RE
+.TP
+\fBwebhook_token_file\fR = "\fI/path/to/file\fR" (optional)
+Path to a file containing the webhook token.
+The file contents are read and trimmed of leading/trailing whitespace.
+Compatible with Docker secrets (\fI/run/secrets/\fR) and Kubernetes secret volumes.
+.RS
+When set, \fBwebhook_token\fR should be omitted (it defaults to empty).
+Cannot be combined with the \fB${VAR}\fR substitution syntax.
+.PP
+\fBSecurity note:\fR Ensure the token file has restrictive permissions
+(e.g., 0400 or 0600) and is readable only by the witryna user.
+.RE
+.SH REPOSITORY CONFIG FILE
+.TP
+\fBconfig_file\fR = "\fIpath\fR" (optional)
+Path to a custom build config file in the repository, relative to the repo root
+(e.g., ".witryna.yaml", "build/config.yml").
+Must be a relative path with no path traversal (\fI..\fR).
+.PP
+If not set, witryna searches the repository root in order:
+\fI.witryna.yaml\fR, \fI.witryna.yml\fR, \fIwitryna.yaml\fR, \fIwitryna.yml\fR.
+The first file found is used.
+.SH BUILD OVERRIDES
+Build parameters can optionally be specified directly in the site definition,
+overriding values from the repository's build config file
+(\fI.witryna.yaml\fR / \fIwitryna.yaml\fR).
+When all three fields (\fBimage\fR, \fBcommand\fR, \fBpublic\fR) are set,
+the repository config file becomes optional.
+.TP
+\fBimage\fR = "\fIcontainer:tag\fR" (optional)
+Container image to use for the build (e.g., "node:20\-alpine").
+Required unless provided in \fIwitryna.yaml\fR.
+Must not be blank.
+.TP
+\fBcommand\fR = "\fIshell command\fR" (optional)
+Build command executed via \fBsh \-c\fR inside the container.
+Must not be blank.
+.TP
+\fBpublic\fR = "\fIrelative/path\fR" (optional)
+Directory containing built static assets, relative to the repository root.
+Must be a relative path with no path traversal (\fI..\fR).
+.SH RESOURCE LIMITS
+Optional resource limits for container builds.
+These flags are passed directly to the container runtime.
+.TP
+\fBcontainer_memory\fR = "\fIsize\fR" (optional)
+Memory limit for the build container (e.g., "512m", "2g", "1024k").
+Must be a number followed by a unit suffix: \fBk\fR, \fBm\fR, or \fBg\fR
+(case\-insensitive).
+Passed as \fB\-\-memory\fR to the container runtime.
+.TP
+\fBcontainer_cpus\fR = \fIn\fR (optional)
+CPU limit for the build container (e.g., 0.5, 2.0).
+Must be greater than 0.
+Passed as \fB\-\-cpus\fR to the container runtime.
+.TP
+\fBcontainer_pids_limit\fR = \fIn\fR (optional)
+Maximum number of PIDs inside the build container (e.g., 100).
+Must be greater than 0.
+Passed as \fB\-\-pids\-limit\fR to the container runtime.
+Helps prevent fork bombs during builds.
+.SH NETWORK ISOLATION
+.TP
+\fBcontainer_network\fR = "\fImode\fR" (optional, default: "bridge")
+Network mode for the build container.
+Passed as \fB\-\-network=\fImode\fR to the container runtime.
+.RS
+Allowed values:
+.IP \(bu 2
+\fB"bridge"\fR (default) \- Standard container networking (NAT).
+Works out of the box for builds that download dependencies (e.g., \fBnpm install\fR).
+.IP \(bu 2
+\fB"none"\fR \- No network access.
+Most secure option; use for builds that don't need to download anything.
+.IP \(bu 2
+\fB"host"\fR \- Use the host network namespace directly.
+.IP \(bu 2
+\fB"slirp4netns"\fR \- User\-mode networking (Podman rootless).
+.PP
+Set \fBcontainer_network = "none"\fR for maximum isolation when your build
+does not require network access.
+.RE
+.SH CONTAINER WORKING DIRECTORY
+.TP
+\fBcontainer_workdir\fR = "\fIpath\fR" (optional, default: repo root)
+Working directory inside the build container, relative to the repository root.
+Useful for monorepo projects where the build runs from a subdirectory.
+.PP
+The value is a relative path (e.g., "packages/frontend") appended to the
+default \fB/workspace\fR mount point, resulting in
+\fB\-\-workdir /workspace/packages/frontend\fR.
+.PP
+Must be a relative path with no path traversal (\fI..\fR) and no leading slash.
+.SH POLLING
+.TP
+\fBpoll_interval\fR = "\fIduration\fR" (optional, default: disabled)
+If set, witryna periodically fetches the remote branch and triggers a build
+when new commits are detected.
+Accepts a \fBhumantime\fR duration string (e.g., "30m", "1h", "2h30m").
+.RS
+Minimum interval is 1 minute.
+Polling respects the concurrent build lock; if a build is already in progress,
+the poll cycle is skipped.
+Initial poll delays are staggered across sites to avoid a thundering herd.
+.RE
+.SH GIT CLONE DEPTH
+.TP
+\fBgit_depth\fR = \fIn\fR (optional, default: 1)
+Git clone depth for the repository.
+.RS
+.IP \(bu 2
+\fB1\fR (default) \- Shallow clone with only the latest commit.
+Fast and minimal disk usage.
+.IP \(bu 2
+\fB0\fR \- Full clone with complete history.
+Required for \fBgit describe\fR or monorepo change detection.
+.IP \(bu 2
+\fBn > 1\fR \- Shallow clone with \fIn\fR commits of history.
+.RE
+.PP
+Submodules are detected and initialized automatically regardless of clone depth.
+.SH BUILD TIMEOUT
+.TP
+\fBbuild_timeout\fR = "\fIduration\fR" (optional, default: "10m")
+Maximum time a build command is allowed to run before being killed.
+Accepts a \fBhumantime\fR duration string (e.g., "5m", "30m", "1h").
+.RS
+Minimum is 10 seconds, maximum is 24 hours.
+.RE
+.SH CACHE VOLUMES
+.TP
+\fBcache_dirs\fR = ["\fI/container/path\fR", ...] (optional)
+List of absolute container paths to persist as cache volumes across builds.
+Each path gets a dedicated host directory under \fI<base_dir>/cache/<site>/\fR.
+.RS
+Validation rules:
+.IP \(bu 2
+Each entry must be an absolute path.
+.IP \(bu 2
+No path traversal (\fI..\fR) allowed.
+.IP \(bu 2
+No duplicates after normalization.
+.IP \(bu 2
+Maximum 20 entries per site.
+.PP
+Common cache paths:
+.TS
+l l.
+Node.js	/root/.npm
+Python pip	/root/.cache/pip
+Go modules	/root/.cache/go
+Rust cargo	/usr/local/cargo/registry
+Maven	/root/.m2/repository
+.TE
+.PP
+Cache directories are \fBnever cleaned automatically\fR by witryna.
+Administrators should monitor disk usage under
+\fI<base_dir>/cache/\fR and prune manually when needed.
+.RE
+.SH ENVIRONMENT VARIABLES
+.TP
+\fB[sites.env]\fR (optional)
+TOML table of environment variables passed to builds and post\-deploy hooks.
+Each key\-value pair becomes a \fB\-\-env KEY=VALUE\fR flag for the container
+runtime.
+Variables are also passed to post\-deploy hooks.
+.RS
+Validation rules:
+.IP \(bu 2
+Keys must not be empty.
+.IP \(bu 2
+Keys must not contain \fB=\fR.
+.IP \(bu 2
+Neither keys nor values may contain null bytes.
+.IP \(bu 2
+Keys starting with \fBWITRYNA_\fR (case\-insensitive) are reserved and rejected.
+.IP \(bu 2
+Maximum 64 entries per site.
+.PP
+In post\-deploy hooks, user\-defined variables are set \fBbefore\fR the reserved
+variables (PATH, HOME, LANG, WITRYNA_*), so they cannot override system or
+Witryna\-internal values.
+.RE
+.SH POST-DEPLOY HOOKS
+.TP
+\fBpost_deploy\fR = ["\fIcmd\fR", "\fIarg\fR", ...] (optional)
+Command to execute after a successful symlink switch.
+Uses array form (no shell interpolation) for safety.
+.RS
+The hook receives context exclusively via environment variables:
+.TP
+\fBWITRYNA_SITE\fR
+The site name.
+.TP
+\fBWITRYNA_BUILD_DIR\fR
+Absolute path to the new build directory (also the working directory).
+.TP
+\fBWITRYNA_PUBLIC_DIR\fR
+Absolute path to the stable current symlink
+(e.g. /var/lib/witryna/builds/my\-site/current).
+Use this as the web server document root.
+.TP
+\fBWITRYNA_BUILD_TIMESTAMP\fR
+Build timestamp (YYYYmmdd-HHMMSS-ffffff).
+.PP
+The hook runs with a minimal environment: any user\-defined variables
+from \fB[sites.env]\fR, followed by PATH, HOME, LANG,
+and the WITRYNA_* variables above (which take precedence).
+Its working directory is the build output directory.
+It is subject to a 30\-second timeout and killed if exceeded.
+Output is streamed to disk and logged to
+\fI<log_dir>/<site>/<timestamp>\-hook.log\fR.
+.PP
+Hook failure is \fBnon\-fatal\fR: the deployment is already live,
+and a warning is logged.
+The exit code is recorded in the hook log.
+A log file is written for every hook invocation (success, failure,
+timeout, or spawn error).
+.PP
+Validation rules:
+.IP \(bu 2
+The array must not be empty.
+.IP \(bu 2
+The first element (executable) must not be empty or whitespace\-only.
+.IP \(bu 2
+No element may contain null bytes.
+.IP \(bu 2
+Maximum 64 elements.
+.RE
+.SH HOT RELOAD
+Sending \fBSIGHUP\fR to the witryna process causes it to re\-read
+\fIwitryna.toml\fR.
+Sites can be added, removed, or reconfigured without downtime.
+Polling tasks are stopped and restarted to reflect the new configuration.
+.PP
+The following fields are \fBnot reloadable\fR and require a full restart:
+.IP \(bu 2
+\fBlisten_address\fR
+.IP \(bu 2
+\fBbase_dir\fR
+.IP \(bu 2
+\fBlog_dir\fR
+.IP \(bu 2
+\fBlog_level\fR
+.PP
+If any of these fields differ after reload, a warning is logged but the new
+values are ignored until the process is restarted.
+.PP
+If the reloaded configuration is invalid, the existing configuration remains
+active and an error is logged.
+.SH EXAMPLES
+A complete annotated configuration:
+.PP
+.nf
+.RS 4
+# Network
+listen_address = "127.0.0.1:8080"
+
+# Container runtime ("podman" or "docker")
+container_runtime = "podman"
+
+# Data directory (clones, builds, cache)
+base_dir = "/var/lib/witryna"
+
+# Log directory (per\-build logs)
+log_dir = "/var/log/witryna"
+
+# Tracing verbosity
+log_level = "info"
+
+# Webhook rate limit (per token, per minute)
+rate_limit_per_minute = 10
+
+# Keep the 5 most recent builds per site
+max_builds_to_keep = 5
+
+# Git operation timeout (clone, fetch, reset)
+# git_timeout = "2m"
+
+# A site that relies on witryna.yaml in the repo
+[[sites]]
+name = "my\-blog"
+repo_url = "https://github.com/user/my\-blog.git"
+branch = "main"
+webhook_token = "s3cret\-tok3n"
+# Or from environment: webhook_token = "${MY_BLOG_TOKEN}"
+# Or from file: webhook_token_file = "/run/secrets/blog\-token"
+poll_interval = "1h"
+
+# A site with full build overrides (no witryna.yaml needed)
+# Custom build timeout (default: 10 minutes)
+[[sites]]
+name = "docs\-site"
+repo_url = "https://github.com/user/docs.git"
+branch = "main"
+webhook_token = "an0ther\-t0ken"
+image = "node:20\-alpine"
+command = "npm ci && npm run build"
+public = "dist"
+build_timeout = "30m"
+cache_dirs = ["/root/.npm"]
+post_deploy = ["curl", "\-sf", "https://status.example.com/deployed"]
+
+# Environment variables for builds and hooks
+[sites.env]
+DEPLOY_TOKEN = "abc123"
+NODE_ENV = "production"
+.fi
+.RE
+.SH SECURITY CONSIDERATIONS
+.TP
+\fBContainer isolation\fR
+Build commands run inside ephemeral containers with \fB\-\-cap\-drop=ALL\fR.
+When the runtime is Podman, \fB\-\-userns=keep\-id\fR is added so the
+container user maps to the host UID, avoiding permission issues without
+any extra capabilities.
+When the runtime is Docker, \fBDAC_OVERRIDE\fR is re\-added because
+Docker runs as root (UID\ 0) inside the container while the workspace is
+owned by the host UID; without this capability, the build cannot read or
+write files.
+The container filesystem is isolated; the build has no direct access to
+the host beyond the mounted workspace directory.
+.SH SYSTEMD OVERRIDES
+The deb and rpm packages install example systemd override templates to
+\fI/usr/share/doc/witryna/examples/systemd/\fR.
+The post\-install script copies the appropriate template to
+\fI/etc/systemd/system/witryna.service.d/10\-runtime.conf\fR based on the
+detected container runtime.
+.TP
+\fBdocker.conf\fR
+.nf
+.RS 4
+[Service]
+SupplementaryGroups=docker
+ReadWritePaths=/var/run/docker.sock
+.fi
+.RE
+.TP
+\fBpodman.conf\fR
+.nf
+.RS 4
+[Service]
+RestrictNamespaces=no
+Environment="XDG_RUNTIME_DIR=/run/user/%U"
+.fi
+.RE
+.PP
+\fB%U\fR resolves to the numeric UID of the service user at runtime.
+To add custom overrides, create a separate file (e.g.,
+\fI20\-custom.conf\fR) in the same directory; do not edit
+\fI10\-runtime.conf\fR as it will be overwritten on package reinstall.
+.SH FILES
+When no \fB\-\-config\fR flag is given, \fBwitryna\fR searches for the
+configuration file in the following order:
+.IP 1. 4
+\fI./witryna.toml\fR (current working directory)
+.IP 2. 4
+\fI$XDG_CONFIG_HOME/witryna/witryna.toml\fR (default: \fI~/.config/witryna/witryna.toml\fR)
+.IP 3. 4
+\fI/etc/witryna/witryna.toml\fR
+.PP
+The first file found is used.
+If none exists, an error is printed listing all searched paths.
+.SH SEE ALSO
+\fBwitryna\fR(1)