# Running from source

This is the path for working on kixctl itself. It is not a quick evaluation route — for that, see [Installing kixctl](../getting-started/install.md) 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:

```bash
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](https://github.com/kixago/kixctl/blob/main/CONTRIBUTING.md) in the main repository, which points back to this page for setup.