Skip to content

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

feat: add cryptographically signed Docker images with Cosign (#136)

FrameAutomatad5814989e95e
diff --git a/.github/workflows/release-traceway.yml b/.github/workflows/release-traceway.yml
index 12dcd878..0ee63e74 100644
--- a/.github/workflows/release-traceway.yml
+++ b/.github/workflows/release-traceway.yml
@@ -31,6 +31,8 @@ on:
permissions:
contents: write
actions: write
+ packages: write
+ id-token: write
jobs:
release:
@@ -160,10 +162,98 @@ jobs:
gh workflow run release-website.yml --ref "${{ github.ref_name }}"
gh workflow run release-docs.yml --ref "${{ github.ref_name }}"
+ build-docker:
+ runs-on: ubuntu-latest
+ needs: release
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v3
+
+ - name: Log in to GitHub Container Registry
+ uses: docker/login-action@v3
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Build and push full image
+ id: docker_build_full
+ uses: docker/build-push-action@v5
+ with:
+ context: .
+ file: ./Dockerfile
+ push: true
+ tags: |
+ ghcr.io/${{ github.repository_owner }}/traceway:v${{ inputs.version }}
+ ghcr.io/${{ github.repository_owner }}/traceway:latest
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+
+ - name: Build and push minimal image
+ id: docker_build_minimal
+ uses: docker/build-push-action@v5
+ with:
+ context: .
+ file: ./Dockerfile.minimal
+ push: true
+ tags: |
+ ghcr.io/${{ github.repository_owner }}/traceway:v${{ inputs.version }}-minimal
+ ghcr.io/${{ github.repository_owner }}/traceway:minimal
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+
+ - name: Build and push SQLite image
+ id: docker_build_sqlite
+ uses: docker/build-push-action@v5
+ with:
+ context: .
+ file: ./Dockerfile.sqlite
+ push: true
+ tags: |
+ ghcr.io/${{ github.repository_owner }}/traceway:v${{ inputs.version }}-sqlite
+ ghcr.io/${{ github.repository_owner }}/traceway:sqlite
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+
+ - name: Install Cosign
+ uses: sigstore/cosign-installer@v3
+ with:
+ cosign-release: 'v2.2.0'
+
+ - name: Sign full image
+ env:
+ COSIGN_EXPERIMENTAL: 1
+ run: |
+ cosign sign --yes ghcr.io/${{ github.repository_owner }}/traceway@${{ steps.docker_build_full.outputs.digest }}
+
+ - name: Sign minimal image
+ env:
+ COSIGN_EXPERIMENTAL: 1
+ run: |
+ cosign sign --yes ghcr.io/${{ github.repository_owner }}/traceway@${{ steps.docker_build_minimal.outputs.digest }}
+
+ - name: Sign SQLite image
+ env:
+ COSIGN_EXPERIMENTAL: 1
+ run: |
+ cosign sign --yes ghcr.io/${{ github.repository_owner }}/traceway@${{ steps.docker_build_sqlite.outputs.digest }}
+
- name: Summary
run: |
- echo "Released backend/v${{ inputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+ echo "### Docker Images (signed with Cosign)" >> "$GITHUB_STEP_SUMMARY"
+ echo "" >> "$GITHUB_STEP_SUMMARY"
+ echo "**Full Image** (ClickHouse + PostgreSQL + supervisord):" >> "$GITHUB_STEP_SUMMARY"
+ echo "\`ghcr.io/${{ github.repository_owner }}/traceway:v${{ inputs.version }}\`" >> "$GITHUB_STEP_SUMMARY"
+ echo "" >> "$GITHUB_STEP_SUMMARY"
+ echo "**Minimal Image** (external ClickHouse/PostgreSQL):" >> "$GITHUB_STEP_SUMMARY"
+ echo "\`ghcr.io/${{ github.repository_owner }}/traceway:v${{ inputs.version }}-minimal\`" >> "$GITHUB_STEP_SUMMARY"
+ echo "" >> "$GITHUB_STEP_SUMMARY"
+ echo "**SQLite Image** (embedded SQLite, single binary, no dependencies):" >> "$GITHUB_STEP_SUMMARY"
+ echo "\`ghcr.io/${{ github.repository_owner }}/traceway:v${{ inputs.version }}-sqlite\`" >> "$GITHUB_STEP_SUMMARY"
echo "" >> "$GITHUB_STEP_SUMMARY"
- echo "Users can now: \`go get github.com/tracewayapp/traceway/backend@v${{ inputs.version }}\`" >> "$GITHUB_STEP_SUMMARY"
+ echo "All images tagged with version, plus \`latest\`, \`minimal\`, and \`sqlite\` respectively." >> "$GITHUB_STEP_SUMMARY"
echo "" >> "$GITHUB_STEP_SUMMARY"
- echo "Website and docs deploys will run automatically on release publish." >> "$GITHUB_STEP_SUMMARY"
+ echo "See [DOCKER_SIGNATURES.md](https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/DOCKER_SIGNATURES.md) to verify image signatures." >> "$GITHUB_STEP_SUMMARY"
diff --git a/DOCKER_SIGNATURES.md b/DOCKER_SIGNATURES.md
new file mode 100644
index 00000000..23376a87
--- /dev/null
+++ b/DOCKER_SIGNATURES.md
@@ -0,0 +1,204 @@
+# Docker Image Signatures
+
+All official Traceway Docker images are cryptographically signed using [Cosign](https://docs.sigstore.dev/cosign/overview/), a CNCF tool for container image signing and verification.
+
+## Why Image Signatures Matter
+
+Signed images provide:
+- **Authenticity**: Verify the image comes from the official Traceway project
+- **Integrity**: Ensure the image hasn't been modified or tampered with
+- **Transparency**: Signatures are publicly verifiable using GitHub's OIDC token
+
+## Available Images
+
+Traceway publishes three Docker image variants to GitHub Container Registry (GHCR):
+
+| Image | Purpose | Size | Best For |
+|-------|---------|------|----------|
+| `ghcr.io/tracewayapp/traceway:v*` | **Full** — ClickHouse + PostgreSQL + supervisord | ~600MB | Large deployments, multi-service setup |
+| `ghcr.io/tracewayapp/traceway:v*-minimal` | **Minimal** — single binary with external databases | ~20-30MB | Kubernetes, scalable setups, external database infrastructure |
+| `ghcr.io/tracewayapp/traceway:v*-sqlite` | **SQLite** — embedded SQLite, single binary, zero dependencies | ~50-80MB | Small VPS, testing, single-server deployments, embedded mode |
+
+All images are cryptographically signed. Pull the latest release:
+
+```bash
+# Full image (all services included)
+docker pull ghcr.io/tracewayapp/traceway:latest
+
+# Minimal image (external databases)
+docker pull ghcr.io/tracewayapp/traceway:minimal
+
+# SQLite image (embedded, no external dependencies)
+docker pull ghcr.io/tracewayapp/traceway:sqlite
+```
+
+## Verifying Signatures
+
+### Install Cosign
+
+**macOS:**
+```bash
+brew install cosign
+```
+
+**Linux:**
+```bash
+wget https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
+sudo mv cosign-linux-amd64 /usr/local/bin/cosign
+sudo chmod +x /usr/local/bin/cosign
+```
+
+**Windows (PowerShell):**
+```powershell
+Invoke-WebRequest -Uri "https://github.com/sigstore/cosign/releases/latest/download/cosign-windows-amd64.exe" -OutFile cosign.exe
+# Add cosign.exe to your PATH
+```
+
+### Verify Signature
+
+```bash
+# Full image
+cosign verify \
+ --certificate-identity-regexp '.*' \
+ --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
+ ghcr.io/tracewayapp/traceway:latest
+
+# Minimal image
+cosign verify \
+ --certificate-identity-regexp '.*' \
+ --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
+ ghcr.io/tracewayapp/traceway:minimal
+
+# SQLite image
+cosign verify \
+ --certificate-identity-regexp '.*' \
+ --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
+ ghcr.io/tracewayapp/traceway:sqlite
+```
+
+### Example Output
+
+A successful verification looks like:
+```
+Verification successful!
+```
+
+If verification fails, the image may have been tampered with and should not be used.
+
+## How Signatures Are Generated
+
+1. **Build & Push**: GitHub Actions builds the Docker image and pushes it to GHCR
+2. **Sign**: Cosign signs the image using GitHub's OIDC token (keyless signing)
+3. **Store**: Signature is stored in GHCR alongside the image
+
+## Using in Docker Compose
+
+```yaml
+version: '3.8'
+
+services:
+ traceway:
+ image: ghcr.io/tracewayapp/traceway:latest
+ # Optionally verify the signature before running:
+ # Run: cosign verify ... ghcr.io/tracewayapp/traceway:latest
+ ports:
+ - "80:80"
+ - "8082:8082"
+ volumes:
+ - clickhouse_data:/var/lib/clickhouse
+ - postgres_data:/var/lib/postgresql/data
+ environment:
+ GIN_MODE: release
+
+volumes:
+ clickhouse_data:
+ postgres_data:
+```
+
+## Minimal Image with External Databases
+
+For scalable deployments with external ClickHouse/PostgreSQL:
+
+```yaml
+version: '3.8'
+
+services:
+ traceway:
+ image: ghcr.io/tracewayapp/traceway:minimal
+ ports:
+ - "80:80"
+ - "8082:8082"
+ environment:
+ GIN_MODE: release
+ CLICKHOUSE_SERVER: clickhouse:9000
+ POSTGRES_HOST: postgres
+ POSTGRES_PORT: 5432
+ # ... other env vars
+
+ clickhouse:
+ image: clickhouse/clickhouse-server:latest
+ # ... configuration
+
+ postgres:
+ image: postgres:15
+ # ... configuration
+```
+
+## SQLite Image (Embedded, Zero Dependencies)
+
+For small deployments, testing, or single-server setups:
+
+```yaml
+version: '3.8'
+
+services:
+ traceway:
+ image: ghcr.io/tracewayapp/traceway:sqlite
+ ports:
+ - "80:80"
+ - "8082:8082"
+ volumes:
+ - traceway_data:/data
+ environment:
+ GIN_MODE: release
+
+volumes:
+ traceway_data:
+```
+
+The SQLite image:
+- Stores all data in `/data/traceway.db` (SQLite database)
+- Stores blobs in `/data/storage` (if using local storage)
+- Requires only one volume mount for all persistent state
+- Perfect for VPS, small instances, or development
+
+To persist data across restarts, mount a host folder or named volume at `/data`:
+
+```bash
+docker run -v /var/lib/traceway:/data ghcr.io/tracewayapp/traceway:sqlite
+```
+
+## Troubleshooting
+
+**"Verification failed" error:**
+- Ensure you're using the correct image URI (with version tag or `latest`)
+- Check your internet connection (Cosign needs to fetch OIDC tokens)
+- Try verifying a different version tag
+
+**"cosign not found":**
+- Ensure Cosign is installed and in your `$PATH`
+- Run `cosign version` to verify installation
+
+**"Certificate verification failed":**
+- This indicates the image signature is invalid
+- Do not use this image — report it to the Traceway team
+
+## More Information
+
+- [Cosign Documentation](https://docs.sigstore.dev/cosign/overview/)
+- [Traceway Self-Hosting Guide](https://docs.tracewayapp.com/server)
+- [SBOM (Software Bill of Materials)](https://docs.sigstore.dev/cosign/sbom/)
+
+## Questions?
+
+If you have questions about Docker image security or signatures, [open an issue](https://github.com/tracewayapp/traceway/issues) or ask in the [Traceway Discord](https://discord.gg/9tPn2SB3).
diff --git a/README.md b/README.md
index 584b81c8..f96a1d1a 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,8 @@ cd traceway && docker compose up -d
Point any OTel SDK at `http://localhost/api/otel/v1/traces` (or `/metrics`, `/logs`) and traces start flowing. See the [self-hosting docs](https://docs.tracewayapp.com/server/docker-compose) for production deployment, TLS, and storage configuration.
+**Docker images are cryptographically signed.** See [DOCKER_SIGNATURES.md](./DOCKER_SIGNATURES.md) to verify images before deploying.
+
### Embedded mode (inside your Go app)
Run Traceway inside your Go process — no Docker, no external databases, SQLite under the hood: