Finaisse Internal Docs

Appearance

New Environment Runbook ​

Use this when provisioning a new Railway environment (e.g. staging-2, qa).

Prerequisites ​

  • RAILWAY_API_TOKEN with access to the project
  • fin-infra repo cloned locally with Bun installed

Steps ​

1. Create environment in Railway dashboard ​

  • Open Railway → select the project → Environments → New Environment
  • Note the new RAILWAY_ENVIRONMENT_ID

2. Copy and fill variable template ​

bash
cp environments/staging/variables.env.example environments/<new-env>/.env
# Edit the file and fill in real values

3. Provision infrastructure ​

bash
cd railway
export RAILWAY_API_TOKEN=...
export RAILWAY_PROJECT_ID=...
export RAILWAY_ENVIRONMENT_ID=<new-env-id>

bun run provision:dry    # Verify what will be created
bun run provision        # Provision all infra + services

This provisions: PostgreSQL, RustFS, Valkey, Temporal, RabbitMQ, and all 6 microservices + frontend.

To provision in stages:

bash
bun run provision:infra     # Infra services only (Postgres, RustFS, Valkey, Temporal)
bun run provision:services  # Microservices + frontend only

4. Initialise databases ​

bash
bun run init-db

Creates the finance and mgmt databases. Run once per environment.

5. Sync environment variables ​

bash
bun run vars:sync

Pushes all shared variables from shared/variables.ts to every backend service.

6. Set secrets manually in Railway dashboard ​

These are never stored in code and must be set by hand in the Railway environment variables UI:

SecretRequired by
JWTSECRETAll backend services
GOOGLE_API_KEYagents, wfw
MINIO_ROOT_PASSWORD / MINIO_ROOT_SECRETKEYRustFS service
RABBITMQ_DEFAULT_PASSRabbitMQ service
RUSTFS_ACCESS_KEY / RUSTFS_SECRET_KEYAll services using object storage
DATABASE_URL / POSTGRES_USER / POSTGRES_PASSWORDAll backend services

7. Deploy services ​

bash
bun run deploy:all

Then verify:

bash
bun run status

Health checks should go green within a minute. Check logs if any service fails to start:

bash
bun run logs -- --service blitz-api

Checklist ​

  • [ ] Environment created in Railway dashboard, ID noted
  • [ ] Variable template copied and filled
  • [ ] Infrastructure provisioned (bun run provision:dry then bun run provision)
  • [ ] Databases initialised (bun run init-db)
  • [ ] Variables synced (bun run vars:sync)
  • [ ] Secrets set in Railway dashboard
  • [ ] Services deployed (bun run deploy:all)
  • [ ] All services healthy (bun run status)