Skip to main content

Running from source

This is the path for working on kixctl itself. It is also, today, the way you bolt kixctl onto an Incus cluster you already run, until a packaged bolt-on lands on the roadmap — so it serves both the contributor and the operator who wants the control plane on an existing fabric. If you'd rather not assemble it, the appliance is now available as a bootable VM image and brings its own Incus. What follows stands up the control plane from source.

kixctl is a Laravel, Livewire, and Filament application on PHP 8.4: a web control plane plus a set of background workers. It keeps its own state in Postgres and runs its queues, cache, and realtime broadcasting through Valkey.

What you provide​

  • PostgreSQL — kixctl's own state: users, roles, sessions, queued jobs. Never a copy of Incus state.
  • Valkey — queues, cache, and broadcasting.
  • An Incus cluster to talk to. On a cluster member, kixctl uses the local Unix socket (INCUS_DRIVER=socket). Remote, it authenticates over HTTPS with a restricted, project-scoped client certificate (INCUS_DRIVER=https).

The toolchain​

The repository ships a Nix flake with a development shell that provides PHP 8.4 and its extensions, Composer, Node, and the Postgres, Valkey, and Incus clients — so the environment is reproducible rather than assembled by hand:

nix develop

Bring-up​

Standard Laravel, pointed at your own infrastructure:

  • Copy .env.example to .env. Set DB_HOST to your Postgres, REDIS_HOST to your Valkey, and the Incus driver (socket when co-located with a cluster member, https with a scoped certificate when remote).
  • php artisan key:generate — writes the application key.
  • php artisan migrate — creates kixctl's own schema.
  • php artisan install:broadcasting — generates the keys the app and the realtime server use to trust each other.

Then run the control plane, its queue workers, and the realtime server. Add the scheduler (php artisan schedule:work) if you want the commit poller to watch registered repositories without webhooks.

Contribution process​

The environment is here; branching, review, and what to run before a pull request live in CONTRIBUTING.md in the main repository, which points back to this page for setup.