Skip to main content

Running from source

This is the path for working on kixctl itself. It is not a quick evaluation route — for that, see Installing kixctl and the appliance on the roadmap. What follows stands up the control plane from source so you can develop against it.

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.