Deploy in a Proxmox LXC

Owned by ngit-ciVerified 0.1.0-rc.2 @ aad99deb773dimported guide

The coordinator is designed to run happily inside an LXC container. The recommended shape is a small Debian/Ubuntu LXC running the coordinator via Docker Compose (so this guide builds on deploy-docker.md).

Container prerequisites

• Nesting must be enabled (Options → Features → Nesting in the Proxmox UI, or features: nesting=1 in the container config). Docker inside LXC requires it. Unprivileged containers are fine on modern kernels — prefer them.
• Size the container for CI work: the effective ceiling for job resource usage is max concurrent jobs × per-job container caps (see Job container resource limits) plus overhead for the coordinator and image storage. Job images run to a few GB of disk.

Install

Inside the container:

# Docker (Debian/Ubuntu)
apt-get update && apt-get install -y git curl
curl -fsSL https://get.docker.com | sh

# ngit-ci via compose
git clone https://gitnostr.com/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-ci.git
cd ngit-ci

Then pick a compose variant:

• Unprivileged LXC (recommended): privileged containers are typically unavailable, which rules out the default dind sidecar. Use the host-socket variant against the LXC's own Docker daemon (the "host" here is the LXC container itself, so the blast radius of the mounted socket is confined to the container):

  DOCKER_GROUP_ID=$(stat -c %g /var/run/docker.sock) \
  NGIT_CI_REPOS='npub1.../ngit#NGIT' \
    docker compose -f docker-compose.host-socket.yml up --build -d

• Privileged LXC / nested privilege available: the default docker-compose.yml (dind sidecar) works as on any Docker host.

Main settings: repos and secrets

The settings most operators need to make explicit are NGIT_CI_REPOS and NGIT_CI_SECRET_<ALIAS>__<NAME>, described in the Docker guide's quick start.

For compose-based LXC deployments, keep secrets in the environment or in a locked-down .env file next to the compose file:

cat > .env <<'EOF'
NGIT_CI_REPOS='npub1.../ngit#NGIT'
NGIT_CI_SECRET_NGIT__DEPLOY_TOKEN=...
EOF
chmod 600 .env
docker compose -f docker-compose.host-socket.yml up --build -d

Secrets are injected only for maintainer-authored triggers and never cross repo boundaries. See per-repo secrets for the full trust model and naming rules.

Set NGIT_CI_BLOSSOM_SERVERS to optionally upload full job logs and workflow artifacts to one or more Blossom servers; empty (the default) disables those uploads.

Configuration, state/persistence, and operations are otherwise exactly as described in deploy-docker.md; the full option reference is configuration.md. In particular, keep the compose coordinator-data volume: if no coordinator key is configured, ngit-ci generates /data/.coordinator.nsec there on first start and reuses it on later starts. If you deliberately provide an identity key and it is invalid, startup fails instead of generating a surprise replacement identity.

Running the binary directly (no Docker-in-LXC)

If you prefer a plain process over compose, build the coordinator with cargo build --release, or download the ngit-ci-<version>-x86_64-unknown-linux-musl.tar.gz archive from its signed NIP-82 release. Inspect the release, then compare the downloaded archive's SHA-256 with the value in its signed asset event before extracting it:

ngit --repo nostr://npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/relay.ngit.dev/ngit-ci \
  release view <version>
sha256sum ngit-ci-<version>-x86_64-unknown-linux-musl.tar.gz
tar -xzf ngit-ci-<version>-x86_64-unknown-linux-musl.tar.gz

Install git and act ≥ 0.2.86 on PATH, provide a Docker-compatible daemon (Docker, or rootless Podman via --docker-host), and run ngit-ci under a systemd unit. The static archive removes the Rust and Nix build dependency; it does not bundle these runtime tools. See configuration.md for host requirements and options. The NixOS module is a worked example of the hardening and environment such a unit should have.

VM-grade sandboxing and KVM

The setups above run jobs in containers, which is appropriate for trusted repositories. The stronger, VM-per-job isolation of ngit-ci-adapter-microvm needs /dev/kvm; inside LXC that requires explicit device passthrough from the Proxmox host, so the adapter is better hosted in a Proxmox VM (with nested virtualisation enabled) or on dedicated hardware, with the coordinator pointing at its socket.