Try Falak locally

The Falak repository ships a simulation (sim/) that runs everything on one machine with Docker: the control plane, three Ubuntu 24.04 containers acting as servers (two app servers and a database server), a builder, a git server and Loki/Tempo/Grafana. It is what the project’s end-to-end tests run against. Use it to explore Falak without cloud machines.

Note

The simulation is a development tool. For a real installation, follow the Quickstart.

Prerequisites

• Docker with about 8 GB of RAM available to it
• Go 1.25, make, jq, curl, openssl
• A clone of github.com/OthmanHaba/falak

Start it

1. Build the agent, CLI and builder binaries (they are mounted into the simulation):

   cd agent && make build && cd ..

2. Start everything and wait until it is healthy (about a minute once images are built):

   cd sim
   make up

3. Set a password for the simulation’s admin user:

   docker compose -p falak-sim --env-file sim.env --env-file .data/secrets.env \
     exec control-plane php artisan falak:admin admin@falak.test --reset-password --password='choose-one'

4. Trust the simulation’s certificate authority (sim/.data/edge-root.crt, created by make ca) and open https://localhost:8443. Log in as admin@falak.test.

What you can run

Command	What it does
make e2e	Infrastructure checks: TLS, the mTLS agent edge, observability, servers
make e2e-deploy	The full product flow through public surfaces only (about 13 minutes cold). ONLY=deploy,release runs selected stages.
make logs / make shell	Follow logs / open a shell
make reset	Wipe volumes and generated secrets, keep caches
make reset-all	Also wipe the package, image and download caches

make e2e-deploy is a good tour of what Falak does. It:

1. creates the first admin, an organization and an API token;
2. creates two app servers and one database server through the API, runs their install commands and waits for real provisioning (FrankenPHP, PHP 8.4, Node, PostgreSQL, nftables firewall, SSH hardening);
3. connects a git server and creates a Laravel 13 site on both app servers (app-1 is the leader);
4. deploys it: one native build, fetch and prepare on both, migrations on the leader only, activation, health checks; then a second commit (zero downtime), a rollback, and a broken release that is rolled back automatically;
5. serves a Laravel site through Octane (FrankenPHP worker mode) with zero failed requests during redeploys;
6. deploys a Bun + Hono TypeScript site;
7. checks APM traces in Tempo, an exception grouped into an Insights issue, and deployment events in Loki.

Ports

The simulation uses non-default ports to avoid clashing with other stacks:

Service	URL
Control plane UI	https://localhost:8443
Grafana	http://localhost:13000 (admin / admin)

Other ports are listed in sim/sim.env.