The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
fixes + minimal build w alpine
dduxc9561703fe21
diff --git a/DOCKER.md b/DOCKER.mdindex fe0b4dcc..e4f20a2e 100644--- a/DOCKER.md+++ b/DOCKER.md@@ -1,24 +1,133 @@# Traceway Docker Deployment-All-in-one Docker container that runs the complete Traceway stack:-- **Frontend**: SvelteKit SPA served via nginx (port 80)-- **Backend**: Go/Gin API server (port 8082)-- **ClickHouse**: Time-series database (internal)+This document covers two deployment options:+1. **Minimal Image** (Recommended) - Small image (~20-30MB) with external ClickHouse+2. **All-in-One Image** - Larger image with systemd, suitable for development-## Build+---++## Minimal Deployment (Recommended)++Lightweight Docker image containing only the Go backend with embedded frontend. Designed for production deployments connecting to an external ClickHouse database.++### Features+- **Image size**: ~20-30MB (Alpine-based)+- **Single binary**: Go backend with embedded SvelteKit frontend+- **External ClickHouse**: Connect to any ClickHouse instance+- **Fast startup**: No init system overhead++### Build++```bash+docker build -f Dockerfile.minimal -t traceway:minimal .+```++### Required Environment Variables++| Variable | Description | Example |+|----------|-------------|---------|+| `APP_TOKEN` | Dashboard authentication token | `your-secret-token` |+| `CLICKHOUSE_SERVER` | ClickHouse host:port | `clickhouse.example.com:9000` |+| `CLICKHOUSE_DATABASE` | Database name | `traceway` |+| `CLICKHOUSE_USERNAME` | DB username | `default` |+| `CLICKHOUSE_PASSWORD` | DB password | `password` |+| `CLICKHOUSE_TLS` | Enable TLS connection | `true` or `false` |++### Run++#### Basic+```bash+docker run -d --name traceway \+ -p 80:80 \+ -e APP_TOKEN="your-app-token" \+ -e CLICKHOUSE_SERVER="your-clickhouse-host:9000" \+ -e CLICKHOUSE_DATABASE="traceway" \+ -e CLICKHOUSE_USERNAME="default" \+ -e CLICKHOUSE_PASSWORD="your-password" \+ traceway:minimal+```++#### With TLS+```bash+docker run -d --name traceway \+ -p 80:80 \+ -e APP_TOKEN="your-app-token" \+ -e CLICKHOUSE_SERVER="your-clickhouse-host:9440" \+ -e CLICKHOUSE_DATABASE="traceway" \+ -e CLICKHOUSE_USERNAME="default" \+ -e CLICKHOUSE_PASSWORD="your-password" \+ -e CLICKHOUSE_TLS="true" \+ traceway:minimal+```++### Docker Compose Example++```yaml+version: '3.8'++services:+ traceway:+ build:+ context: .+ dockerfile: Dockerfile.minimal+ ports:+ - "80:80"+ environment:+ APP_TOKEN: "your-app-token"+ CLICKHOUSE_SERVER: "clickhouse:9000"+ CLICKHOUSE_DATABASE: "traceway"+ CLICKHOUSE_USERNAME: "default"+ CLICKHOUSE_PASSWORD: "your-password"+ depends_on:+ - clickhouse++ clickhouse:+ image: clickhouse/clickhouse-server:24.3+ ports:+ - "9000:9000"+ - "8123:8123"+ volumes:+ - clickhouse-data:/var/lib/clickhouse++volumes:+ clickhouse-data:+```++### Verify Image Size++```bash+docker images traceway:minimal+# Expected: ~20-30MB+```++### Access Points++| URL | Description |+|-----|-------------|+| `http://localhost/` | Frontend (SvelteKit SPA) |+| `http://localhost/api/*` | Backend API |+| `http://localhost/health` | Health check endpoint |++---++## All-in-One Deployment (with systemd)++Larger Docker image using systemd for process management. Suitable for development or when you want built-in process supervision.++### Build```bashdocker build -t traceway:latest .```-## Run+### Run-### Basic+#### Basic```bashdocker run -d --name traceway -p 80:80 -p 8082:8082 traceway:latest```-### With Persistent Data (Recommended)+#### With Persistent Data (Recommended)```bashdocker run -d --name traceway \-p 80:80 \@@ -27,7 +136,7 @@ docker run -d --name traceway \traceway:latest```-### With Custom Tokens+#### With Custom Tokens```bashdocker run -d --name traceway \-p 80:80 \@@ -38,7 +147,7 @@ docker run -d --name traceway \traceway:latest```-## Access Points+### Access Points| URL | Description ||-----|-------------|@@ -46,6 +155,8 @@ docker run -d --name traceway \| `http://localhost/api/*` | Backend API (proxied through nginx) || `http://localhost:8082/api/*` | Direct backend access |+---+## Useful Commands```bash@@ -55,33 +166,24 @@ docker logs traceway# Follow logsdocker logs -f traceway-# Check service status-docker exec traceway supervisorctl status-# Enter container shell-docker exec -it traceway bash+docker exec -it traceway sh # minimal image (alpine)+docker exec -it traceway bash # all-in-one image (debian)++# Check health+curl http://localhost/health# Stop containerdocker stop traceway# Stop and removedocker stop traceway && docker rm traceway--# Remove with data volume-docker stop traceway && docker rm traceway && docker volume rm traceway-data```-## Architecture--The container uses **supervisord** to manage three services:--1. **ClickHouse** (priority 10) - Starts first-2. **Backend** (priority 20) - Waits for ClickHouse, then starts-3. **Nginx** (priority 30) - Starts last, serves frontend and proxies API+---## Notes-- First startup takes ~60 seconds while ClickHouse initializes- Backend automatically runs database migrations on startup-- Use `-v traceway-data:/var/lib/clickhouse` to persist data between restarts-- Environment variables `TOKEN` and `APP_TOKEN` can be overridden at runtime+- The minimal image starts in under 1 second+- For production, always use the minimal image with external ClickHouse for better reliability and scalabilitydiff --git a/Dockerfile b/Dockerfileindex 7486d408..e46fc06e 100644--- a/Dockerfile+++ b/Dockerfile@@ -25,7 +25,7 @@ RUN npm run build# ==============================================================================# Stage 2: Build Backend with embedded frontend# ==============================================================================-FROM golang:1.24-alpine AS backend-builder+FROM golang:1.25-alpine AS backend-builderWORKDIR /app/backend@@ -38,8 +38,8 @@ COPY backend/ ./# Copy built frontend to static/dist for embeddingCOPY --from=frontend-builder /app/frontend/build ./static/dist/-# Fix go version and download deps-RUN go mod edit -go=1.24 && go mod download+# Download dependencies+RUN go mod download# Build with embedded static filesRUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o /traceway .diff --git a/Dockerfile.minimal b/Dockerfile.minimalnew file mode 100644index 00000000..801a93c0--- /dev/null+++ b/Dockerfile.minimal@@ -0,0 +1,78 @@+# ==============================================================================+# Traceway Minimal Docker Image+# Single binary serving both API and Frontend+# Designed for small instances with external ClickHouse+# Target image size: ~20-30MB+# ==============================================================================++# ==============================================================================+# Stage 1: Build Frontend+# ==============================================================================+FROM node:22-alpine AS frontend-builder++WORKDIR /app/frontend++# Copy package files first for better caching+COPY frontend/package.json frontend/package-lock.json ./++# Install dependencies+RUN npm ci++# Copy source and build+COPY frontend/ ./++RUN npm run build++# ==============================================================================+# Stage 2: Build Backend with embedded frontend+# ==============================================================================+FROM golang:1.25-alpine AS backend-builder++WORKDIR /app/backend++# Install build dependencies+RUN apk add --no-cache git++# Copy all backend source+COPY backend/ ./++# Copy built frontend to static/dist for embedding+COPY --from=frontend-builder /app/frontend/build ./static/dist/++# Download dependencies+RUN go mod download++# Build with embedded static files+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o /traceway .++# ==============================================================================+# Stage 3: Minimal runtime image+# ==============================================================================+FROM alpine:3.20++# Install minimal runtime dependencies+# - ca-certificates: for HTTPS connections to external ClickHouse+# - tzdata: for timezone support+RUN apk add --no-cache ca-certificates tzdata++# Copy the binary+COPY --from=backend-builder /traceway /usr/local/bin/traceway++# Create app directory+WORKDIR /app++# Environment variables (can be overridden at runtime)+ENV GIN_MODE=release+ENV ENABLE_PORT_80=true++# Expose ports+# 80: Frontend + API (when ENABLE_PORT_80=true)+# 8082: Direct API access+EXPOSE 80 8082++# Health check using wget (alpine-native, no curl needed)+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \+ CMD wget -qO- http://localhost/health || exit 1++# Run the binary directly (no systemd needed)+ENTRYPOINT ["/usr/local/bin/traceway"]diff --git a/backend/main.go b/backend/main.goindex a3c968c7..74cea698 100644--- a/backend/main.go+++ b/backend/main.go@@ -22,12 +22,10 @@ import ()func main() {- err := godotenv.Load()- if err != nil {- // we don't actually care for the .env file existing- // because in production we can just deploy with container variables- panic(fmt.Errorf("error loading the .env file: %w", err))- }+ // we don't actually care for the .env file existing+ // because in production we can just deploy with container variables+ // so the error is ignored+ godotenv.Load()appToken := os.Getenv("APP_TOKEN")if appToken == "" {