Skip to content
This repository was archived by the owner on Mar 21, 2026. It is now read-only.

README.md

Latest commit

 

History

History
65 lines (41 loc) · 3.04 KB

README.md

File metadata and controls

65 lines (41 loc) · 3.04 KB

fleet.nix — GitOps for Proxmox + NixOS

This repository contains a Nix flake to manage NixOS and Darwin configurations and helper scripts to deploy them to Proxmox LXC containers. It also includes tooling to create and register GitHub self-hosted runners.

Overview

  • scripts/deploy.sh — Consolidated deployment script (interactive and CI modes, and LXC creation).
  • scripts/deploy-lxc.sh — Backwards-compatible wrapper that calls deploy.sh create-lxc.
  • scripts/create-github-runner.sh — Creates a Proxmox LXC (or uses an existing one) and installs a GitHub Actions self-hosted runner.
  • .github/workflows/deploy.yml — Workflow that runs on pushes to main and executes the ci deploy on a self-hosted runner.

Prerequisites

  • A GitHub repository (this repo) with appropriate permissions.
  • A Proxmox host with API/CLI access from the runner (or run the runner on the Proxmox host directly).
  • Nix installed on the runner host (recommended for deployment operations).
  • SSH access to the Proxmox host and to created containers (for creation and runner setup).

Usage

Local Interactive Deploy

  • Run ./scripts/deploy.sh local
  • Select a nixosConfiguration from the flake using fzf.

CI / Non-interactive Deploy

  • On a self-hosted runner (Linux), pushing to main will trigger .github/workflows/deploy.yml which runs ./scripts/deploy.sh ci.
  • Ensure the self-hosted runner has the following installed: nix, jq, git, and network access to your Proxmox host if you plan to create LXC containers.

Create an LXC (manual)

  • Example: ./scripts/deploy.sh create-lxc -h proxmox.local -i 101 -n haproxy -p 10.0.0.10 -c haproxy
  • The script will create an LXC using the latest NixOS template and push ./hosts/<config>/configuration.nix if provided.

Create and Register a GitHub Runner

  1. Generate a registration token in your GitHub repo or org (Settings → Actions → Runners → New self-hosted runner → Generate token).
  2. Run the script with required args: ./scripts/create-github-runner.sh --proxmox-host proxmox.local --id 120 --name runner01 --ip 10.0.0.20 --github-url https://github.com/OWNER/REPO --token <REGISTRATION_TOKEN>

The script will:

  • Optionally create the LXC (unless --skip-create is passed).
  • Wait for SSH on the container.
  • Download the latest actions/runner release and configure it using the provided token.

Notes on Security

  • Keep your GitHub registration token secret and short-lived.
  • For production use, create a dedicated GitHub Actions runner user and harden access.

Troubleshooting

  • If the workflow does not run on your server, ensure the runner is online and labeled self-hosted and linux.
  • Check runner logs in the container (/home/actions/actions-runner/_diag) for errors.
  • If SSH times out during runner creation, ensure the container has network and SSH enabled.

Contributing

  • Open a PR with small, focused changes. Describe the changes and include testing steps.

License

  • This repository follows the license indicated in the upstream project (if any). Check repository root for license information.