Install Tasuku

Run commands from the Tasuku repository root.

Development stack

The development Compose file supplies local-only defaults for the bootstrap token and master key. It runs Vite on port 5173 and the bundled control plane on port 8080.

docker compose -f docker-compose.dev.yml --profile build build
docker compose -f docker-compose.dev.yml up --build

Open http://localhost:5173 for Vite hot reload. Use http://localhost:8080 as the target for a public tunnel because that is the server GitHub must reach.

Production topology

Create a .env file from .env.example, then set at least DATABASE_URL, TASUKU_PUBLIC_URL, TASUKU_BOOTSTRAP_TOKEN, and TASUKU_MASTER_KEY.

Generate the master key once:

openssl rand -base64 32

Start the production topology:

docker compose -f docker-compose.yml up --build -d

This starts Postgres, runs migrations to completion, starts the server, and starts an independent worker. The bundled agent runtime image is built before the worker begins.

Railway

Tasuku includes service-scoped Railway configs for both supported topologies:

/railway.json — one service running tasuku all.
/railway.server.json — the public server in split mode; it runs database migrations before deployment and checks /readyz.
/railway.worker.json — the background worker in split mode; it runs database migrations before deployment and has no public endpoint or HTTP health check.

For split mode, connect the server and worker services to the same repository and select the corresponding config path in each service's settings. Share the application variables and Postgres DATABASE_URL between them, but expose only the server. Set TASUKU_PUBLIC_URL to its final HTTPS origin.

All three process configs use Railway's pre-deploy phase for migrations. The migrator takes a PostgreSQL advisory lock, so split server and worker deployments can begin independently without racing the schema update. Do not model migration as a separate Railway service dependency: Railway does not apply dependency ordering to independent GitHub-push deployments.

When Cloudflare proxies Railway, use Full (strict) SSL/TLS mode. Flexible mode can loop between Cloudflare's HTTPS edge and Railway's HTTPS redirect.

Keep the master key stable

Back up the exact active and previous key ring and restore it with the database. Do not replace TASUKU_MASTER_KEY directly; follow the master-key rotation runbook so the old key remains available while ciphertext is rewritten.

Verify the server

The health check is unversioned:

curl --fail http://localhost:8080/healthz
curl --fail http://localhost:8080/readyz

The production Compose file maps ${TASUKU_PORT:-8080} on the host to port 8080 in the server container. Postgres uses its named tasuku-postgres volume.

Verify the worker

The worker has no public HTTP endpoint. Inspect its structured logs and confirm it starts without database, master-key, runtime-image, or provider errors:

docker compose -f docker-compose.yml logs worker

First-run setup

Open the dashboard. The first-run flow creates the installation organization and authorizes GitHub App manifest registration. Browser authorization is held in an HttpOnly cookie for five minutes.

You can create the organization directly through the API:

curl -X POST http://localhost:8080/api/v1/bootstrap \
  -H "Authorization: Bearer $TASUKU_BOOTSTRAP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"organization_name":"Acme"}'

Continue with Create and install the GitHub App.