From ce0dbf6b249956700c6a1705bf4ad85a09d53e8c Mon Sep 17 00:00:00 2001 From: Dawid Rycerz Date: Sun, 15 Feb 2026 21:27:00 +0100 Subject: feat: witryna 0.2.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Switch, cleanup, and status CLI commands. Persistent build state via state.json. Post-deploy hooks on success and failure with WITRYNA_BUILD_STATUS. Dependency diet (axum→tiny_http, clap→argh, tracing→log). Drop built-in rate limiting. Nix flake with NixOS module. Arch Linux PKGBUILD. Centralized version management. Co-Authored-By: Claude Opus 4.6 --- man/witryna.1 | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 man/witryna.1 (limited to 'man/witryna.1') 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//\fR +Git repository clones. +.TP +\fI/var/lib/witryna/builds///\fR +Timestamped build outputs. +.TP +\fI/var/lib/witryna/builds//current\fR +Symlink to the latest successful build. +.TP +\fI/var/lib/witryna/builds//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//\fR +Persistent build cache volumes. +.TP +\fI/var/log/witryna//.log\fR +Per\-build log files (site, timestamp, git commit, image, duration, status, stdout, stderr). +.TP +\fI/var/log/witryna//\-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 -- cgit v1.2.3