Skip to content
Sooke Community App

Common Commands

This document lists the commands needed to run, build, and manage the project. It is updated as new tools and services are added.

Documentation (Starlight)

Section titled “Documentation (Starlight)”

The documentation site uses Starlight, an Astro-based static site generator. The Starlight project lives in the starlight-docs/ directory. The source markdown files are maintained in docs/ and copied into starlight-docs/src/content/docs/ with frontmatter added.

Prerequisites

Section titled “Prerequisites”
  • Node.js 18 or later
  • npm (included with Node.js)

Install dependencies

Section titled “Install dependencies”
Terminal window
cd starlight-docs
npm install

Run the documentation site locally

Section titled “Run the documentation site locally”
Terminal window
cd starlight-docs
npm run dev

This starts a local development server with hot reload. Open the URL shown in the terminal (typically http://localhost:4321).

Build the documentation site for production

Section titled “Build the documentation site for production”
Terminal window
cd starlight-docs
npm run build

This generates a static site in starlight-docs/dist/. The output can be deployed to Cloudflare Pages or any static hosting provider.

Preview the production build locally

Section titled “Preview the production build locally”
Terminal window
cd starlight-docs
npm run preview

This serves the built static site locally so you can verify the production output before deploying.

Go Server

Section titled “Go Server”

The backend API is written in Go using Chi. The API lives in the server/ directory.

Prerequisites

Section titled “Prerequisites”
  • A supported Go toolchain (see server/go.mod for the minimum required version)

Install dependencies

Section titled “Install dependencies”
Terminal window
cd server
go mod download

Run API Locally

Section titled “Run API Locally”
Terminal window
cd server
go run ./cmd/api

The server defaults to port 8080. Set the PORT environment variable to change the port.

Build the binary

Section titled “Build the binary”
Terminal window
cd server
go build -o bin/api ./cmd/api

This will produce an executable binary at server/bin/api that can be run on the target platform.

Run tests

Section titled “Run tests”
Terminal window
cd server
go test ./...

This runs all unit tests. Integration tests that require a database are skipped when TEST_DATABASE_URL is not set.

Run tests with database (integration)

Section titled “Run tests with database (integration)”
Terminal window
cd server
TEST_DATABASE_URL="<your_test_database_url>" go test ./...

This runs the full test suite including integration tests that verify database connectivity.

PostgreSQL

Section titled “PostgreSQL”

The development database runs on the developer’s NAS. See ADR-008 for why we chose this over Docker. Connection details (host, port, credentials) are configured via environment variables in .env.

The database client used for manual inspection is TablePlus on macOS.

Environment setup

Section titled “Environment setup”
  1. Copy .env.example to .env at the project root.
  2. Fill in the real values for DATABASE_URL and TEST_DATABASE_URL.
  3. The .env file is gitignored and must never be committed.

The Go API loads .env automatically at startup via godotenv. In production (Railway), environment variables are set directly — no .env file is needed.

Verify the connection

Section titled “Verify the connection”

Start the API and hit the health endpoint:

Terminal window
cd server
go run ./cmd/api
Terminal window
curl http://localhost:8080/api/v1/health

Expected response when the database is reachable:

{ "status": "ok", "db_status": "connected" }

Sections to Add Later

Section titled “Sections to Add Later”

The following sections will be added as each tool or service is set up:

  • SvelteKit mobile app (run, test, build)
  • Capacitor (iOS build, Android build, sync)
  • PostgreSQL migrations and seed data
  • Admin dashboard (run, test, build, deploy)
  • Cloudflare R2 (upload, configure)
  • Clerk (configure, test tokens)