Skip to main content

Getting Started

Prerequisites​

  • Git
  • Node.js 20+ (Angular dev server runs on Node)
  • Bun 1.3+ (backend + workspace scripts)
  • Docker optional but recommended for parity testing
  • Cloudflare account (optional, only for the Worker build)

Install dependencies​

 git clone https://github.com/bobbyquantum/inkweld.git
 cd inkweld
 bun install

This installs all dependencies for the root, Angular frontend, and Bun backend.

Configure environment files​

 # From project root
 cp .env.example .env

Key backend settings (see .env.example at project root):

  • PORT, HOST, CLIENT_URL
  • DB_TYPE, DB_PATH, DATA_PATH
  • SESSION_SECRET, ALLOWED_ORIGINS
  • Optional GitHub OAuth flags

Run in development​

From the repo root, start both servers with one command:

 npm run dev

That launches the Bun backend on port 8333 and the Angular dev server on port 4200. If you prefer to control them independently:

 # Backend (Bun runtime)
 cd backend
 bun run dev

 # Alternative runners
 bun run dev:node
 bun run dev:worker

 # Frontend (Bun runs Angular CLI via Node.js)
 cd ../frontend
 bun run start

Testing and linting​

 # Full workspace helpers (from root)
 bun run lint
 bun run test

 # Backend only
 cd backend
 bun run lint
 bun test

 # Frontend only
 cd ../frontend
 bun run lint
 bun test
 bun run e2e

Frontend unit tests use Vitest, while end-to-end coverage runs through Playwright with fixtures in frontend/e2e/fixtures.ts. Backend tests run via Bun.

Building artifacts​

Frontend​

 cd frontend
 bun run clean
 bun run build
 bun run compress   # optional bundle compression

Backend​

 cd backend
 bun run build          # Bun target
 bun run build:node     # Node target
 bun run build:worker   # Cloudflare Worker preview

Backend builds land in backend/dist/ and include the Bun runner, the Node runner, and Worker bundles.

Docker and Compose​

The Dockerfile bundles the Angular production build into a single Bun binary that serves both the SPA and API from the same container. Access http://localhost:8333/ for the frontend and /api/** for the API.

docker build -t inkweld .
docker run -p 8333:8333 -v inkweld_data:/data \
  -e SESSION_SECRET=supersecuresecretkey12345678901234567890 \
  inkweld

Key runtime notes:

  • SESSION_SECRET must be 32+ characters.
  • Mount /data to persist SQLite database and Yjs documents between restarts.
  • Set SERVE_FRONTEND=false to run in API-only mode (if hosting frontend separately).
  • Drizzle migrations run automatically on container start.

For compose-based deployments:

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

See Deployment → Docker for production-focused guidance.

Cloudflare Worker / Durable Objects​

 cd backend
 cp wrangler.toml.example wrangler.toml
 npx wrangler d1 create inkweld_dev
 npx wrangler d1 create inkweld_prod
 bun run deploy:dev

Add your D1 IDs and Durable Object bindings to wrangler.toml, then use bun run logs:dev (or logs:prod) to inspect deployments.

Admin CLI quick reference​

The Bun-based CLI (backend/admin-cli.ts) manages users, projects, and stats without requiring the UI:

 cd backend

 # Inspect pending registrations
 bun run admin users pending

 # Approve a user
 bun run admin users approve <username>

 # Review overall stats
 bun run admin stats

Inside Docker you can reuse the CLI against the running container:

docker exec -it inkweld \
   ./inkweld-server admin users approve <username>

The CLI loads the same .env values as the backend, so double-check database paths before pointing it at production data.

Verify the Docker image locally​

docker build -t inkweld:dev .
docker run --rm -p 8333:8333 \
  -e SESSION_SECRET=supersecuresecretkey12345678901234567890 \
  inkweld:dev
curl http://localhost:8333/api/v1/health

For multi-platform testing, use BuildKit: docker buildx build --platform linux/amd64,linux/arm64 --load -t inkweld:dev .

Next steps​