# Witryna

Witryna is a minimalist Git-based static site deployment orchestrator.
It listens for webhook triggers, pulls Git repositories, runs
containerized build commands, and publishes static assets via atomic
symlink switching.

## How it works

A webhook POST triggers Witryna to pull a Git repository (with
automatic submodule initialization and Git LFS fetch), run a build
command inside a container, copy the output to a timestamped directory,
and atomically switch a symlink to the new build.
Your web server serves files from the symlink — zero-downtime deploys.

## Install

Pre-built packages are available at
[release.craftknight.com](https://release.craftknight.com/).

From a `.deb` package (Debian/Ubuntu):

    curl -LO https://release.craftknight.com/witryna_0.2.0-1_amd64.deb
    sudo dpkg -i witryna_0.2.0-1_amd64.deb

From an `.rpm` package (Fedora/RHEL):

    curl -LO https://release.craftknight.com/witryna-0.2.0-1.x86_64.rpm
    sudo rpm -i witryna-0.2.0-1.x86_64.rpm

From PKGBUILD (Arch Linux):

    git clone https://git.craftknight.com/dawid/witryna.git
    cd witryna/arch && makepkg -si

With Nix (flake):

    nix profile install git+https://git.craftknight.com/dawid/witryna

NixOS module:

    # In your flake.nix inputs:
    witryna.url = "git+https://git.craftknight.com/dawid/witryna";

    # In your NixOS configuration:
    services.witryna = {
      enable = true;
      configFile = "/etc/witryna/witryna.toml";
    };

From a tarball (any Linux):

    curl -LO https://release.craftknight.com/witryna-0.2.0-linux-amd64.tar.gz
    tar xzf witryna-0.2.0-linux-amd64.tar.gz
    sudo cp witryna-0.2.0-linux-amd64/witryna /usr/local/bin/

From source:

    cargo install --path .

## Post-install

The deb/rpm packages automatically detect your container runtime:

- **Docker**: `witryna` user added to `docker` group, systemd override installed
- **Podman**: subuids/subgids allocated, lingering enabled, systemd override installed
- **Neither found**: warning with instructions

If you install a runtime later, reinstall the package or manually copy the
override from `/usr/share/doc/witryna/examples/systemd/` to
`/etc/systemd/system/witryna.service.d/10-runtime.conf` and run
`sudo systemctl daemon-reload`.

## Quickstart

1. Create `/etc/witryna/witryna.toml`:

    ```toml
    listen_address = "127.0.0.1:8080"
    container_runtime = "podman"
    base_dir = "/var/lib/witryna"
    log_level = "info"

    [[sites]]
    name = "my-site"
    repo_url = "https://github.com/user/my-site.git"
    branch = "main"
    webhook_token = "YOUR_TOKEN"  # omit to disable auth
    ```

2. Add a build config to the root of your Git repository (`.witryna.yaml`,
   `.witryna.yml`, `witryna.yaml`, or `witryna.yml`):

    ```yaml
    image: node:20-alpine
    command: "npm ci && npm run build"
    public: dist
    ```

3. Start Witryna:

    ```
    witryna serve
    ```

4. Trigger a build:

    ```
    TOKEN=...  # your webhook_token from witryna.toml
    curl -X POST -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/my-site
    # If webhook_token is omitted, the -H header is not needed.
    ```

## CLI

| Command | Description |
|---------|-------------|
| `witryna serve` | Start the deployment server |
| `witryna validate` | Validate config and print summary |
| `witryna run <site>` | Run a one-off build (synchronous) |
| `witryna status` | Show deployment status |
| `witryna switch <site> <build>` | Switch active build (rollback) |
| `witryna cleanup [site]` | Remove old builds and logs |

## Configuration

Witryna searches for its config file automatically: `./witryna.toml`,
`$XDG_CONFIG_HOME/witryna/witryna.toml`, `/etc/witryna/witryna.toml`.
Use `--config` to specify an explicit path.

See `witryna.toml(5)` for the full configuration reference:

    man witryna.toml

Build config supports `.witryna.yaml`, `.witryna.yml`, `witryna.yaml`, and
`witryna.yml` (searched in that order). See `examples/` for annotated files.

## Reverse proxy

Point your web server's document root at
`/var/lib/witryna/builds/<site>/current` and reverse-proxy webhook
requests to Witryna. See `examples/caddy/` and `examples/nginx/` for
ready-to-use configurations.

## Building from source

    cargo build --release

Development uses [just](https://github.com/casey/just) as a command runner:

    cargo install just    # or: pacman -S just / brew install just

Key recipes:

    just test             # unit tests
    just test-all         # lints + unit + integration tests
    just lint             # fmt check + clippy + yamllint + gitleaks

To build distribution packages:

    just build-deb    # Debian .deb package
    just build-rpm    # RPM package
    just build-arch   # Arch Linux package
    just build-nix    # Nix package

## Dependencies

- Rust 1.85+ (build only)
- Git
- Podman or Docker

## License

MIT — see LICENSE for details.