# Try Falak locally

> Run the full Falak stack on your laptop in Docker — a control plane, three Ubuntu 24.04 servers, a builder, a git server and the observability stack.

Source: https://falak.sh/docs/getting-started/local-simulation/

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.

The simulation is a development tool. For a real installation, follow the [Quickstart](/docs/getting-started/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](https://github.com/OthmanHaba/falak)

## Start it

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

   ```bash
   cd agent && make build && cd ..
   ```

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

   ```bash
   cd sim
   make up
   ```

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

   ```bash
   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`.