The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
docs: pre-built Docker images + contributor charter (#161)
FrameAutomata00d562ce7e26
diff --git a/docs/pages/learn/contributing.mdx b/docs/pages/learn/contributing.mdxindex 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 upstreamgit 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.mdxindex 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 VariablesAll 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.mdxindex 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.mdxindex 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.mdxindex 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 SQLitAll 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).