Skip to content

The only tool you need to know what is happening and how to fix it.

docs: pre-built Docker images + contributor charter (#161)

FrameAutomata00d562ce7e26
diff --git a/docs/pages/learn/contributing.mdx b/docs/pages/learn/contributing.mdx
index 1673c47a..bb62c32f 100644
--- a/docs/pages/learn/contributing.mdx
+++ b/docs/pages/learn/contributing.mdx
@@ -2,7 +2,33 @@
import { Callout } from "nextra/components";
-This guide covers how to set up the Traceway development environment, run tests, and submit changes.
+This guide covers how to contribute to Traceway — from filing an issue to getting a PR merged.
+
+## Community
+
+The fastest way to ask questions, share ideas, or get help from maintainers is [Discord](https://discord.gg/9tPn2SB3). Issues and PRs are the right place for concrete bugs and changes; Discord is for everything else.
+
+## Opening Issues
+
+### Bug reports
+
+Search open issues first to avoid duplicates. When you file a bug, include:
+
+- **What happened** — a clear description of the bug
+- **What you expected** — what should have happened instead
+- **Steps to reproduce** — the smallest sequence of steps that triggers it
+- **Environment** — Traceway version, deployment type (SQLite, Docker Compose, all-in-one), OS
+- **Logs** — any relevant error messages or stack traces
+
+The more precise the reproduction steps, the faster the fix.
+
+### Feature requests
+
+Open an issue before writing code. Describe the problem you're solving and what you have in mind. This avoids building something that conflicts with existing plans, duplicates in-progress work, or doesn't fit the project's direction. A quick conversation upfront saves everyone time.
+
+### Labels
+
+Maintainers add labels after the issue is filed. You don't need to set them yourself.
## Project Structure
@@ -271,3 +297,35 @@ Then create a pull request on GitHub. Include:
git fetch upstream
git rebase upstream/main
```
+
+## PR Review Process
+
+All pull requests require **at least one approving review** before merging. This applies to everyone, including maintainers.
+
+### What reviewers look at
+
+- **Correctness** — does the code do what the PR says it does?
+- **Testing** — are the requirements in "Before submitting" met? Repository changes need the pgch Docker tests to pass.
+- **Patterns** — does the change follow the conventions in [CLAUDE.md](https://github.com/tracewayapp/traceway/blob/main/CLAUDE.md)? Reviewers will push back on divergence from established patterns.
+- **Scope** — is the PR focused? A small, focused PR is always preferred over one that mixes unrelated changes.
+
+### Merge strategy
+
+PRs are squash-merged, so write a clear PR title and description — they become the commit message on `main`. Don't just say "fix bug"; say what bug, why it happened, and what you changed.
+
+### Review timeline
+
+Maintainers aim to review PRs within a few days. If a PR has been open for more than a week with no response, ping in Discord. If you push new commits after requesting review, leave a comment explaining what changed — don't silently update the branch.
+
+## Using AI Tools
+
+AI-assisted contributions are welcome. Claude Code, Copilot, and similar tools can speed up boilerplate and help explore options.
+
+Ground rules:
+
+- **Review everything.** You are responsible for every line in your PR regardless of whether AI wrote it. Read the diff. Understand it. If you don't understand something, figure it out before submitting — reviewers will ask.
+- **Test it yourself.** Don't rely on AI saying "this should work." Run the code. Run the tests listed in "Before submitting."
+- **Architecture matters.** AI doesn't know the conventions in this repo. Cross-check generated code against [CLAUDE.md](https://github.com/tracewayapp/traceway/blob/main/CLAUDE.md) — especially the error handling patterns, transaction middleware, and repository patterns.
+- **Say so in the PR description.** Mention that you used AI assistance so reviewers know to look carefully at novel patterns or structural choices.
+
+There is no stigma around AI usage here — just shared responsibility for quality.
diff --git a/docs/pages/server/all-in-one.mdx b/docs/pages/server/all-in-one.mdx
index 231b4bb2..21a5ea52 100644
--- a/docs/pages/server/all-in-one.mdx
+++ b/docs/pages/server/all-in-one.mdx
@@ -2,15 +2,29 @@
Single Docker container with ClickHouse, PostgreSQL, and the Go backend managed by supervisord. Best for simple setups where you want everything in one place.
-## Build
+## Quick Start
+
+Pull the pre-built image from GitHub Container Registry:
```bash
-docker build -t traceway:latest .
+docker pull ghcr.io/tracewayapp/traceway:latest
+
+docker run -d --name traceway \
+ -p 80:80 \
+ -v traceway-ch:/var/lib/clickhouse \
+ -v traceway-pg:/var/lib/postgresql/data \
+ ghcr.io/tracewayapp/traceway:latest
```
-## Run
+After starting, open `http://localhost/register` to create your first account.
+
+## Build from Source
+
+Only needed if you want to run a custom or modified build:
```bash
+docker build -t traceway:latest .
+
docker run -d --name traceway \
-p 80:80 \
-v traceway-ch:/var/lib/clickhouse \
@@ -18,8 +32,6 @@ docker run -d --name traceway \
traceway:latest
```
-After starting, open `http://localhost/register` to create your first account.
-
## Environment Variables
All environment variables have working defaults, no configuration required. Override as needed:
diff --git a/docs/pages/server/docker-compose.mdx b/docs/pages/server/docker-compose.mdx
index 7e49c4f2..63625d1b 100644
--- a/docs/pages/server/docker-compose.mdx
+++ b/docs/pages/server/docker-compose.mdx
@@ -1,22 +1,84 @@
# Docker Compose
-Runs Traceway, ClickHouse, and PostgreSQL as separate services. Uses the [Minimal Container](/server/minimal) image with databases managed by Docker Compose.
+Runs Traceway, ClickHouse, and PostgreSQL as separate services using the [Minimal Container](/server/minimal) image.
## Quick Start
-```bash
-# Start the full stack (builds images and starts all services)
-docker compose up --build
+No build required — use the pre-built image from GitHub Container Registry with this `docker-compose.yml`:
+
+```yaml
+services:
+ traceway:
+ image: ghcr.io/tracewayapp/traceway:minimal
+ ports:
+ - "80:80"
+ environment:
+ CLICKHOUSE_SERVER: "clickhouse:9000"
+ CLICKHOUSE_DATABASE: "traceway"
+ CLICKHOUSE_USERNAME: "default"
+ CLICKHOUSE_PASSWORD: "clickhouse"
+ CLICKHOUSE_TLS: "false"
+ POSTGRES_HOST: "postgres"
+ POSTGRES_PORT: "5432"
+ POSTGRES_DATABASE: "traceway"
+ POSTGRES_USERNAME: "traceway"
+ POSTGRES_PASSWORD: "traceway"
+ POSTGRES_SSLMODE: "disable"
+ JWT_SECRET: "change-this-to-a-secure-secret-at-least-32-chars"
+ depends_on:
+ clickhouse:
+ condition: service_healthy
+ postgres:
+ condition: service_healthy
+ restart: unless-stopped
+
+ clickhouse:
+ image: clickhouse/clickhouse-server:24.8-alpine
+ environment:
+ CLICKHOUSE_DB: traceway
+ CLICKHOUSE_PASSWORD: clickhouse
+ volumes:
+ - clickhouse-data:/var/lib/clickhouse
+ healthcheck:
+ test: ["CMD", "clickhouse-client", "--password", "clickhouse", "--query", "SELECT 1"]
+ interval: 5s
+ timeout: 3s
+ start_period: 10s
+ retries: 10
+ restart: unless-stopped
+
+ postgres:
+ image: postgres:17
+ environment:
+ POSTGRES_USER: traceway
+ POSTGRES_PASSWORD: traceway
+ POSTGRES_DB: traceway
+ volumes:
+ - postgres-data:/var/lib/postgresql/data
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U traceway"]
+ interval: 5s
+ timeout: 3s
+ start_period: 10s
+ retries: 10
+ restart: unless-stopped
+
+volumes:
+ clickhouse-data:
+ postgres-data:
+```
-# Clean restart (removes volumes, resets all data)
-docker compose down -v && docker compose up --build
+```bash
+docker compose up -d
```
After starting, open `http://localhost/register` to create your first account.
+The `docker-compose.yml` in the repository root builds from source instead. Use that if you are actively developing Traceway or need to run a modified build (`docker compose up --build`).
+
## Configuration
-The `docker-compose.yml` in the repository root is ready to use out of the box. To customize, edit the environment variables in the file directly:
+Edit the environment variables in your compose file as needed:
| Variable | Default | Description |
|----------|---------|-------------|
diff --git a/docs/pages/server/minimal.mdx b/docs/pages/server/minimal.mdx
index 404f7d68..b3ea2697 100644
--- a/docs/pages/server/minimal.mdx
+++ b/docs/pages/server/minimal.mdx
@@ -2,15 +2,13 @@
Lightweight Alpine image (~20-30MB) containing only the Go backend with the embedded frontend. Requires external ClickHouse and PostgreSQL instances.
-## Build
+## Quick Start
-```bash
-docker build -f Dockerfile.minimal -t traceway:minimal .
-```
-
-## Run
+Pull the pre-built image and run it pointing at your databases:
```bash
+docker pull ghcr.io/tracewayapp/traceway:minimal
+
docker run -d --name traceway \
-p 80:80 \
-e CLICKHOUSE_SERVER="clickhouse-host:9000" \
@@ -25,11 +23,21 @@ docker run -d --name traceway \
-e POSTGRES_SSLMODE="disable" \
-e JWT_SECRET="your-jwt-secret-min-32-characters-long" \
-e APP_BASE_URL="https://traceway.example.com" \
- traceway:minimal
+ ghcr.io/tracewayapp/traceway:minimal
```
After starting, open `http://localhost/register` to create your first account.
+## Build from Source
+
+Only needed if you want to run a custom or modified build:
+
+```bash
+docker build -f Dockerfile.minimal -t traceway:minimal .
+```
+
+Then use `traceway:minimal` instead of `ghcr.io/tracewayapp/traceway:minimal` in the command above.
+
## Required Environment Variables
| Variable | Description | Example |
diff --git a/docs/pages/server/sqlite.mdx b/docs/pages/server/sqlite.mdx
index 73091afc..31a62702 100644
--- a/docs/pages/server/sqlite.mdx
+++ b/docs/pages/server/sqlite.mdx
@@ -4,27 +4,35 @@ Smallest possible Traceway deployment: a single Alpine container that uses SQLit
All persistent state — both SQLite database files and blob storage — lives under `/data`. Bind-mount that single folder to keep your data across restarts.
-## Build
+## Quick Start
-```bash
-docker build -f Dockerfile.sqlite -t traceway:sqlite .
-```
-
-## Run (local storage)
+Pull the pre-built image and run it with a persistent data volume:
```bash
+docker pull ghcr.io/tracewayapp/traceway:sqlite
+
docker run -d --name traceway \
-p 80:80 \
-v "$(pwd)/traceway-data:/data" \
-e JWT_SECRET="your-jwt-secret-min-32-characters-long" \
-e APP_BASE_URL="https://traceway.example.com" \
- traceway:sqlite
+ ghcr.io/tracewayapp/traceway:sqlite
```
Both SQLite files (`traceway.db`, `traceway_telemetry.db`) and uploaded blobs (under `storage/`) land inside the mounted folder.
After starting, open `http://localhost/register` to create your first account.
+## Build from Source
+
+Only needed if you want to run a custom or modified build:
+
+```bash
+docker build -f Dockerfile.sqlite -t traceway:sqlite .
+```
+
+Then use `traceway:sqlite` instead of `ghcr.io/tracewayapp/traceway:sqlite` in the commands above.
+
## Run (S3 storage)
To offload blob storage to S3 (or any S3-compatible service like MinIO, Cloudflare R2, or DigitalOcean Spaces), set `STORAGE_TYPE=s3` and provide the S3 credentials. SQLite still lives on disk under `/data`.
@@ -39,7 +47,7 @@ docker run -d --name traceway \
-e S3_REGION="us-east-1" \
-e S3_ACCESS_KEY="your-access-key" \
-e S3_SECRET_KEY="your-secret-key" \
- traceway:sqlite
+ ghcr.io/tracewayapp/traceway:sqlite
```
For non-AWS providers add `-e S3_ENDPOINT="https://s3.example.com"`. If `S3_ACCESS_KEY` and `S3_SECRET_KEY` are omitted, the AWS SDK falls back to the default credential chain (IAM role, environment, shared config).