Skip to content

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

sqlite based docker deploy + railway deploy info

ddux93d8b6de1e69
diff --git a/Dockerfile.sqlite b/Dockerfile.sqlite
new file mode 100644
index 00000000..a971e059
--- /dev/null
+++ b/Dockerfile.sqlite
@@ -0,0 +1,72 @@
+# ==============================================================================
+# Traceway SQLite Docker Image
+# Single binary serving API and Frontend with embedded SQLite.
+# No external databases required. Optional S3 for blob storage.
+# ==============================================================================
+
+# ==============================================================================
+# Stage 1: Build Frontend
+# ==============================================================================
+FROM node:22-alpine AS frontend-builder
+
+WORKDIR /app/frontend
+
+COPY frontend/package.json frontend/package-lock.json ./
+
+RUN npm ci
+
+COPY frontend/ ./
+
+ENV CLOUD_MODE=false
+RUN npm run build
+
+# ==============================================================================
+# Stage 2: Build Backend with embedded frontend (no pgch tag = SQLite mode)
+# ==============================================================================
+FROM golang:1.25-alpine AS backend-builder
+
+WORKDIR /app/backend
+
+RUN apk add --no-cache git
+
+COPY backend/ ./
+
+COPY --from=frontend-builder /app/frontend/build ./static/frontend/
+
+RUN go mod edit -dropreplace=go.tracewayapp.com -dropreplace=go.tracewayapp.com/tracewaygin
+RUN go mod tidy
+RUN go mod download
+
+# Build WITHOUT the pgch tag so the SQLite codepath in app/db/db_sqlite.go
+# is selected. modernc.org/sqlite is pure Go, so CGO_ENABLED=0 is fine.
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o /traceway ./cmd/traceway
+
+# ==============================================================================
+# Stage 3: Minimal runtime image
+# ==============================================================================
+FROM alpine:3.20
+
+RUN apk add --no-cache ca-certificates tzdata
+
+COPY --from=backend-builder /traceway /usr/local/bin/traceway
+
+RUN mkdir -p /data && chmod 755 /data
+
+WORKDIR /app
+
+# SQLite databases and local blob storage both live under /data so a single
+# bind-mount or named volume covers all persistent state.
+ENV GIN_MODE=release \
+ DB_TYPE=sqlite \
+ SQLITE_PATH=/data/traceway.db \
+ STORAGE_TYPE=local \
+ STORAGE_PATH=/data/storage
+
+VOLUME ["/data"]
+
+EXPOSE 80 8082
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+ CMD wget -qO- http://localhost/health || exit 1
+
+ENTRYPOINT ["/usr/local/bin/traceway"]
diff --git a/docker-compose.sqlite.yml b/docker-compose.sqlite.yml
new file mode 100644
index 00000000..89013066
--- /dev/null
+++ b/docker-compose.sqlite.yml
@@ -0,0 +1,31 @@
+services:
+ traceway:
+ build:
+ context: .
+ dockerfile: Dockerfile.sqlite
+ ports:
+ - "80:80"
+ environment:
+ JWT_SECRET: "change-this-to-a-secure-secret-at-least-32-chars"
+ # APP_BASE_URL: "https://traceway.example.com"
+
+ # Optional: store blobs (source maps, session recordings, AI traces) in S3
+ # instead of the local /data/storage folder.
+ # STORAGE_TYPE: "s3"
+ # S3_BUCKET: "your-bucket"
+ # S3_REGION: "us-east-1"
+ # S3_ACCESS_KEY: "your-access-key"
+ # S3_SECRET_KEY: "your-secret-key"
+ # S3_ENDPOINT: "https://s3.example.com" # for MinIO / R2 / Spaces
+ volumes:
+ - traceway-data:/data
+ restart: unless-stopped
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://localhost/health"]
+ interval: 30s
+ timeout: 3s
+ start_period: 5s
+ retries: 3
+
+volumes:
+ traceway-data:
diff --git a/docs/components/DeploymentCards.jsx b/docs/components/DeploymentCards.jsx
index 009a67c5..1d20fda9 100644
--- a/docs/components/DeploymentCards.jsx
+++ b/docs/components/DeploymentCards.jsx
@@ -23,6 +23,13 @@ const DEPLOYMENTS = [
description:
"Lightweight Alpine image (~20-30MB). Connect to your own external ClickHouse and PostgreSQL.",
},
+ {
+ title: "SQLite",
+ href: "/server/sqlite",
+ subtitle: "Backend + Frontend + SQLite",
+ description:
+ "Single Alpine container with embedded SQLite. No external databases needed. Optional S3 for source maps and recordings.",
+ },
{
title: "Local Setup",
href: "/server/local-setup",
diff --git a/docs/pages/server/_meta.json b/docs/pages/server/_meta.json
index 66fb3775..8e683557 100644
--- a/docs/pages/server/_meta.json
+++ b/docs/pages/server/_meta.json
@@ -3,6 +3,7 @@
"all-in-one": "All-in-One Container",
"docker-compose": "Docker Compose",
"minimal": "Minimal Container",
+ "sqlite": "SQLite",
"local-setup": "Local Setup",
"haloy": "Haloy"
}
diff --git a/docs/pages/server/sqlite.mdx b/docs/pages/server/sqlite.mdx
new file mode 100644
index 00000000..5f4c82be
--- /dev/null
+++ b/docs/pages/server/sqlite.mdx
@@ -0,0 +1,139 @@
+# SQLite
+
+Smallest possible Traceway deployment: a single Alpine container that uses SQLite for both the main database and telemetry, with the frontend embedded into the Go binary. No external Postgres or ClickHouse required. Blob storage (source maps, session recordings, AI traces) is written to a local folder by default and can optionally be backed by S3.
+
+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
+
+```bash
+docker build -f Dockerfile.sqlite -t traceway:sqlite .
+```
+
+## Run (local storage)
+
+```bash
+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
+```
+
+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.
+
+## 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`.
+
+```bash
+docker run -d --name traceway \
+ -p 80:80 \
+ -v "$(pwd)/traceway-data:/data" \
+ -e JWT_SECRET="your-jwt-secret-min-32-characters-long" \
+ -e STORAGE_TYPE="s3" \
+ -e S3_BUCKET="your-bucket" \
+ -e S3_REGION="us-east-1" \
+ -e S3_ACCESS_KEY="your-access-key" \
+ -e S3_SECRET_KEY="your-secret-key" \
+ 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).
+
+If `STORAGE_TYPE` is unset (or set to `local`), blobs are written to `/data/storage`, the same volume as the SQLite files — no extra mounts needed.
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JWT_SECRET` | *(required)* | JWT signing secret, minimum 32 characters |
+| `APP_BASE_URL` | *(unset)* | Public URL of your instance. Used for SDK setup snippets and password-reset emails |
+| `SQLITE_PATH` | `/data/traceway.db` | Main SQLite file. Telemetry DB is derived as `<path>_telemetry.db` |
+| `STORAGE_TYPE` | `local` | Blob storage backend. `local` or `s3` |
+| `STORAGE_PATH` | `/data/storage` | Folder for local blob storage. Ignored when `STORAGE_TYPE=s3` |
+| `S3_BUCKET` | *(unset)* | Required when `STORAGE_TYPE=s3` |
+| `S3_REGION` | *(unset)* | Required when `STORAGE_TYPE=s3` |
+| `S3_ACCESS_KEY` | *(unset)* | Optional. Falls back to the default AWS credential chain when unset |
+| `S3_SECRET_KEY` | *(unset)* | Optional. Pair with `S3_ACCESS_KEY` |
+| `S3_ENDPOINT` | *(unset)* | Optional. Set for S3-compatible providers (MinIO, R2, Spaces). Enables path-style URLs |
+| `PORTS` | `80,8082` | Comma-separated list of HTTP ports the server should listen on |
+| `GIN_MODE` | `release` | Gin runtime mode |
+
+## Persistence
+
+The image declares `VOLUME ["/data"]`. Mount a host folder or a named volume there to keep everything across restarts:
+
+```
+/data/
+├── traceway.db # users, organizations, projects, ...
+├── traceway.db-wal # SQLite WAL
+├── traceway.db-shm # SQLite shared memory
+├── traceway_telemetry.db # endpoints, exceptions, spans, metrics, ...
+├── traceway_telemetry.db-wal
+├── traceway_telemetry.db-shm
+└── storage/ # source maps, session recordings, AI traces (when STORAGE_TYPE=local)
+```
+
+Backup tip: stop the container or use `sqlite3 traceway.db ".backup '/path/to/backup.db'"` for a hot backup. WAL files are required for crash recovery, so when copying files manually, copy `*.db`, `*.db-wal`, and `*.db-shm` together.
+
+## Access Points
+
+| URL | Description |
+|-----|-------------|
+| `http://localhost/` | Frontend dashboard |
+| `http://localhost/api/*` | Backend API |
+| `http://localhost/health` | Health check |
+
+## Useful Commands
+
+```bash
+# View logs
+docker logs traceway
+docker logs -f traceway
+
+# Enter container shell
+docker exec -it traceway sh
+
+# Health check
+curl http://localhost/health
+
+# Hot backup of the main database
+docker exec traceway sh -c "apk add --no-cache sqlite >/dev/null && sqlite3 /data/traceway.db \".backup '/data/traceway.backup.db'\""
+
+# Stop and remove (data survives in the mounted volume)
+docker stop traceway && docker rm traceway
+```
+
+## Deploying to Railway
+
+[Railway](https://railway.app) builds and runs the image from your GitHub repository, mounts a persistent volume at `/data`, and gives you a public HTTPS URL — a great fit for the SQLite deployment.
+
+**1. Connect the repo.** Push the project to GitHub, then in Railway choose **New Project → Deploy from GitHub repo** and pick the Traceway repository.
+
+**2. Point Railway at `Dockerfile.sqlite`.** Open **Settings → Build** on the service and set **Custom Dockerfile Path** to `Dockerfile.sqlite`. Railway will use that Dockerfile for every deploy.
+
+**3. Add a volume at `/data`.** Open **Settings → Volumes**, add a new volume, and set the mount path to `/data`. Without this, your SQLite files and uploaded blobs get wiped on every redeploy.
+
+**4. Set environment variables.** Open **Variables** and add:
+
+| Variable | Value | Notes |
+|----------|-------|-------|
+| `JWT_SECRET` | a random string ≥ 32 chars | Required. Generate with `openssl rand -hex 32` |
+| `PORTS` | `${{PORT}}` | Railway exposes a single port via `PORT`. The app's `PORTS` setting accepts a single value, so this binds the server where Railway expects it |
+| `APP_BASE_URL` | `https://<your-service>.up.railway.app` | Optional but recommended once you generate a domain. Makes SDK snippets and reset emails point at the right URL |
+
+To use external object storage, also set `STORAGE_TYPE=s3`, `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, and optionally `S3_ENDPOINT`. Otherwise blobs are written to `/data/storage` on the volume you added above.
+
+**5. Generate a domain.** Open **Settings → Networking → Generate Domain**. Once Railway returns the `*.up.railway.app` URL, update `APP_BASE_URL` to match and redeploy.
+
+**6. Create the first user.** Visit `https://<your-domain>/register` and create your account and organization. The first registered user automatically becomes the organization owner.
+
+**7. Point your SDKs at the new instance.**
+
+```
+<project_token>@https://<your-domain>/api/report
+```