path: root/man/witryna.1

.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