Skip to content

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

fixes + minimal build w alpine

dduxc9561703fe21
diff --git a/DOCKER.md b/DOCKER.md
index 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
```bash
docker build -t traceway:latest .
```
-## Run
+### Run
-### Basic
+#### Basic
```bash
docker run -d --name traceway -p 80:80 -p 8082:8082 traceway:latest
```
-### With Persistent Data (Recommended)
+#### With Persistent Data (Recommended)
```bash
docker run -d --name traceway \
-p 80:80 \
@@ -27,7 +136,7 @@ docker run -d --name traceway \
traceway:latest
```
-### With Custom Tokens
+#### With Custom Tokens
```bash
docker 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 logs
docker 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 container
docker stop traceway
# Stop and remove
docker 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 scalability
diff --git a/Dockerfile b/Dockerfile
index 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-builder
WORKDIR /app/backend
@@ -38,8 +38,8 @@ COPY backend/ ./
# Copy built frontend to static/dist for embedding
COPY --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 files
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o /traceway .
diff --git a/Dockerfile.minimal b/Dockerfile.minimal
new file mode 100644
index 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.go
index 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 == "" {