diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/witryna.1 | 131 | ||||
| -rw-r--r-- | man/witryna.toml.5 | 24 |
2 files changed, 142 insertions, 13 deletions
diff --git a/man/witryna.1 b/man/witryna.1 new file mode 100644 index 0000000..473d395 --- /dev/null +++ b/man/witryna.1 @@ -0,0 +1,131 @@ +.TH witryna 1 2026-02-15 "witryna 0.2.0" +.SH NAME +witryna \- Minimalist Git\-based static site deployment orchestrator +.SH SYNOPSIS +\fBwitryna\fR <\fIcommand\fR> [\fB\-\-config\fR \fIFILE\fR] [\fIargs\fR] +.SH DESCRIPTION +Minimalist Git\-based static site deployment orchestrator. +.PP +Witryna listens for webhook HTTP requests, pulls the corresponding Git +repository (with automatic Git LFS fetch and submodule initialization), +runs a user\-defined build command inside an ephemeral container and +publishes the resulting assets via atomic symlink switching. +.PP +A health\-check endpoint is available at GET /health (returns 200 OK). +.PP +Witryna does not serve files, terminate TLS, or manage DNS. +It is designed to sit behind a reverse proxy (Nginx, Caddy, etc.). +.SH "SUBCOMMANDS" +.TP +\fBserve\fR [\fB\-\-config\fR \fIFILE\fR] +Start the deployment server (foreground). +.TP +\fBvalidate\fR [\fB\-\-config\fR \fIFILE\fR] +Validate configuration file and print summary. +.TP +\fBrun\fR [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-\-config\fR \fIFILE\fR] \fIsite\fR +Trigger a one\-off build for a site (synchronous, no server). +Use \fB\-v\fR to stream full build output to stderr in real\-time. +.TP +\fBstatus\fR [\fB\-\-json\fR] [\fB\-\-config\fR \fIFILE\fR] [\fIsite\fR] +Show deployment status for configured sites. +If \fIsite\fR is given, show the last 10 deployments for that site. +Use \fB\-\-json\fR for machine\-readable JSON output. +A \fB+\fR marker indicates the active deployment (the build the \fBcurrent\fR symlink points to). +.TP +\fBswitch\fR [\fB\-\-config\fR \fIFILE\fR] \fIsite\fR \fIbuild\fR +Switch the active build for a site. Atomically updates the \fBcurrent\fR symlink +to point to the specified build timestamp. Use \fBwitryna status\fR \fIsite\fR to +list available builds with their timestamps. Does not run post\-deploy hooks. +.TP +\fBcleanup\fR [\fB\-\-keep\fR \fIN\fR] [\fB\-\-config\fR \fIFILE\fR] [\fIsite\fR] +Remove old builds and logs. +If \fIsite\fR is given, clean only that site; otherwise clean all. +\fB\-\-keep\fR \fIN\fR overrides the \fBmax_builds_to_keep\fR config value. +.SH OPTIONS +.TP +\fB\-\-config\fR \fIFILE\fR +Path to the configuration file (available on every subcommand). +If not specified, searches: ./witryna.toml, $XDG_CONFIG_HOME/witryna/witryna.toml, +/etc/witryna/witryna.toml. +.TP +\fB\-\-help\fR +Print help information. +.SH "SIGNALS" +.TP +\fBSIGHUP\fR +Reload configuration from \fIwitryna.toml\fR without restarting the server. +Sites can be added, removed, or modified on the fly. +Changes to \fBlisten_address\fR, \fBbase_dir\fR, \fBlog_dir\fR, +and \fBlog_level\fR are detected but require a full restart to take effect; +a warning is logged when these fields differ. +.TP +\fBSIGTERM\fR, \fBSIGINT\fR +Initiate graceful shutdown. +In\-progress builds are allowed to finish before the process exits. +.SH "EXIT STATUS" +.TP +\fB0\fR +Clean shutdown after SIGTERM/SIGINT (\fBserve\fR), configuration valid (\fBvalidate\fR), +build succeeded (\fBrun\fR), status displayed (\fBstatus\fR), or build switched (\fBswitch\fR). +Post\-deploy hook failure is non\-fatal and still exits 0. +Hooks run on both successful and failed builds. +.TP +\fB1\fR +Startup failure, validation error, build failure, site not found, configuration error, +or command\-line usage error (unknown flag, missing subcommand, etc.). +.SH "INSTALLATION" +When installed via deb or rpm packages, the post\-install script automatically +detects the available container runtime and configures system\-level access: +.TP +\fBDocker\fR +The \fBwitryna\fR user is added to the \fBdocker\fR group and a systemd +override is installed at +\fI/etc/systemd/system/witryna.service.d/10\-runtime.conf\fR +granting access to the Docker socket. +.TP +\fBPodman\fR +Subordinate UID/GID ranges are allocated (100000\-165535), user lingering is +enabled, and a systemd override is installed that disables +\fBRestrictNamespaces\fR and sets \fBXDG_RUNTIME_DIR\fR. +.PP +If neither runtime is found at install time, a warning is printed. +Install a runtime and reinstall the package, or manually copy the appropriate +override template from \fI/usr/share/doc/witryna/examples/systemd/\fR to +\fI/etc/systemd/system/witryna.service.d/10\-runtime.conf\fR. +.SH "FILES" +.TP +\fI/etc/witryna/witryna.toml\fR +Conventional configuration path for system\-wide installs. +The shipped systemd unit passes \fB\-\-config /etc/witryna/witryna.toml\fR +explicitly; without \fB\-\-config\fR the CLI defaults to \fIwitryna.toml\fR +in the current working directory. +.TP +\fI/var/lib/witryna/clones/<site>/\fR +Git repository clones. +.TP +\fI/var/lib/witryna/builds/<site>/<timestamp>/\fR +Timestamped build outputs. +.TP +\fI/var/lib/witryna/builds/<site>/current\fR +Symlink to the latest successful build. +.TP +\fI/var/lib/witryna/builds/<site>/state.json\fR +Current build state (building, success, failed, hook\ failed). +Written atomically at each pipeline phase; read by \fBwitryna status\fR +to show in\-progress builds with elapsed time. +.TP +\fI/var/lib/witryna/cache/<site>/\fR +Persistent build cache volumes. +.TP +\fI/var/log/witryna/<site>/<timestamp>.log\fR +Per\-build log files (site, timestamp, git commit, image, duration, status, stdout, stderr). +.TP +\fI/var/log/witryna/<site>/<timestamp>\-hook.log\fR +Post\-deploy hook output (if configured). +.SH "SEE ALSO" +\fBwitryna.toml\fR(5) +.SH VERSION +v0.2.0 +.SH AUTHORS +Dawid Rycerz diff --git a/man/witryna.toml.5 b/man/witryna.toml.5 index 29c0331..78a6ece 100644 --- a/man/witryna.toml.5 +++ b/man/witryna.toml.5 @@ -1,11 +1,11 @@ -.TH WITRYNA.TOML 5 "2026-02-10" "witryna 0.1.0" "Witryna Configuration" +.TH WITRYNA.TOML 5 "2026-02-15" "witryna 0.2.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 +logging, 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 @@ -38,13 +38,9 @@ Directory for per\-build log files. Layout: \fI<log_dir>/<site>/<timestamp>.log\fR .TP \fBlog_level\fR = "\fIlevel\fR" (required) -Tracing verbosity. +Log 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. @@ -54,6 +50,7 @@ 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). +See also: \fBwitryna cleanup\fR for manual pruning. .TP \fBgit_timeout\fR = "\fIduration\fR" (optional, default: "1m") Maximum time allowed for each git operation (clone, fetch, reset, submodule update). @@ -309,7 +306,7 @@ Witryna\-internal values. .SH POST-DEPLOY HOOKS .TP \fBpost_deploy\fR = ["\fIcmd\fR", "\fIarg\fR", ...] (optional) -Command to execute after a successful symlink switch. +Command to execute after every build completion (success or failure). Uses array form (no shell interpolation) for safety. .RS The hook receives context exclusively via environment variables: @@ -327,6 +324,9 @@ Use this as the web server document root. .TP \fBWITRYNA_BUILD_TIMESTAMP\fR Build timestamp (YYYYmmdd-HHMMSS-ffffff). +.TP +\fBWITRYNA_BUILD_STATUS\fR +Build outcome: "success" or "failed". .PP The hook runs with a minimal environment: any user\-defined variables from \fB[sites.env]\fR, followed by PATH, HOME, LANG, @@ -336,8 +336,9 @@ 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. +Hook failure is \fBnon\-fatal\fR and a warning is logged. +On successful builds the deployment is already live; on failed builds +the hook still runs but no assets were published. The exit code is recorded in the hook log. A log file is written for every hook invocation (success, failure, timeout, or spawn error). @@ -393,9 +394,6 @@ 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 |