Local Setup

Run your self-hosted Scrawn billing backend locally for development. Docker Compose setup with PostgreSQL, ClickHouse, and the dashboard.

This guide covers running Scrawn backend locally for development and deploying it to production.

CLI Setup

The Scrawn CLI automates the entire local development stack - PostgreSQL, ClickHouse, server, and dashboard - with a few commands.

Initialize the Stack

Generate the docker-compose file and environment secrets:

bunx scrawn@latest init

This creates a .scrawn/ directory with scrawn.docker-compose.yml, scrawn.env, and initialization SQL.

Prerequisites

You need Docker and Docker Compose installed. The CLI uses them to run the infrastructure services.

Start the Stack

bunx scrawn@latest start

This starts the full Scrawn stack - PostgreSQL, ClickHouse, the gRPC server, and the dashboard - with docker compose. All services run in the background.

Configure the SDK

// scrawn/biller.ts
import { scrawn } from "@scrawn/core";
import { TAGS, EXPRESSIONS } from "./pricerefs";

export const biller = scrawn({
  apiKey: process.env.SCRAWN_KEY as `scrn_${string}`,
  baseURL: "http://localhost:8060",
  httpUrl: "http://localhost:8060",
  // Run `bunx scrawn@latest tags sync` in your terminal
  tags: TAGS,
  expressions: EXPRESSIONS,
});

If you run the backend manually (without the bundled Docker stack), use port 8069 for baseURL and port 8070 for httpUrl.

Stop and Reset

bunx scrawn@latest stop   # Graceful stop, preserves data
bunx scrawn@latest reset  # Wipes all data volumes

Next Steps

SDK Reference

Learn how to use the Scrawn SDK in your application