Deployment Guide

This guide covers how to build, configure, and deploy SourceSeal from local development through production.

Development Setup

Prerequisites

Tool	Version	Purpose
Go	1.22+	Build the CLI and API server
Docker	20.10+	Container runtime for services and Fabric network
Docker Compose	v2+	Orchestrate multi-container deployments
Make	any	Build automation

bash

go version              # Should print go1.22 or later
docker info             # Should succeed (Docker daemon running)
docker compose version  # Should print v2.x

Build from Source

bash

git clone https://github.com/sourceseal/sourceseal.git
cd sourceseal
make build

# Binaries are placed in ./bin/
ls bin/
# sourceseal         (CLI)
# sourceseal-server  (API server)

Run in Development Mode

Development mode uses in-memory stores and a stub Fabric client. No external dependencies are required.

bash

# Start the API server (no auth, in-memory storage, stub blockchain)
SOURCESEAL_DEV_MODE=true ./bin/sourceseal-server

# Verify it is running
curl http://localhost:8080/healthz
# {"status":"ok"}

Initialize the CLI

bash

./bin/sourceseal init

Creates ~/.sourceseal/ with an Ed25519 key pair and a config pointing to http://localhost:8080.

Docker Compose

App Services Only (External Fabric)

Starts PostgreSQL, MinIO, and the SourceSeal API server:

bash

docker compose -f deployments/docker-compose.yaml up -d

PostgreSQL 15 -- Attestation metadata store (port 5432)
MinIO -- S3-compatible SBOM storage (port 9000, console on 9001)
SourceSeal API -- REST API server (port 8080)

Full Stack (Including Fabric Network)

bash

docker compose -f deployments/docker-compose.yaml --profile fabric up -d

Additionally starts: Fabric CA (port 7054), Fabric Orderer (port 7050), Fabric Peer (port 7051), and CouchDB (port 5984).

bash

# Or use the Makefile shortcuts
make docker-up    # Start full stack
make docker-down  # Stop everything

Fabric Network Setup

For a dedicated Fabric network (outside of Docker Compose), use the setup script:

bash

./network/setup.sh

This script:

Checks prerequisites (Docker, Docker Compose, peer CLI)
Downloads Hyperledger Fabric 2.5.6 binaries and Docker images
Generates crypto material using cryptogen
Creates channel artifacts (genesis block, channel transaction)
Starts the Fabric network containers
Creates the sourceseal-channel and joins the peer
Packages, installs, approves, and commits the sourceseal-cc chaincode
Runs a test invocation to verify the deployment

Connecting the Server to Fabric

bash

./bin/sourceseal-server \
  --fabric-peer https://localhost:7053 \
  --fabric-channel sourceseal-channel \
  --fabric-chaincode sourceseal-cc \
  --fabric-msp Org1MSP \
  --fabric-cert /path/to/client.crt \
  --fabric-key /path/to/client.key \
  --fabric-tls-cert /path/to/tlsca.pem

Production Checklist

TLS

Configure --tls-cert and --tls-key on the API server
Use certificates from a trusted CA
Enable TLS on Fabric peer, orderer, and CA connections

Authentication

Set SOURCESEAL_API_KEYS to strong, randomly generated keys (min 32 chars)
Do not set SOURCESEAL_DEV_MODE=true in production
Rotate API keys periodically

Database

Use --store-type=postgres with a dedicated PostgreSQL instance
Enable SSL on the PostgreSQL connection
Configure regular database backups

Object Storage

Use --sbom-store-type=s3 for durable SBOM storage
Set dedicated IAM credentials with minimal permissions
Enable server-side encryption on the S3 bucket

Network

Place the API server behind a reverse proxy (nginx, Envoy)
Set SOURCESEAL_TRUST_PROXY=true when using a reverse proxy
Restrict Docker Compose port bindings to 127.0.0.1
Configure SOURCESEAL_CORS_ORIGINS to allow only your frontend domain(s)

Environment Variables

API Server

Variable	Default	Description
`SOURCESEAL_API_KEYS`	—	Comma-separated list of valid API keys for authentication
`SOURCESEAL_DEV_MODE`	—	Set to true to allow unauthenticated access when no API keys are configured
`SOURCESEAL_CORS_ORIGINS`	`http://localhost:3000`	Comma-separated allowed CORS origins
`SOURCESEAL_S3_ACCESS_KEY`	—	S3 access key for SBOM storage
`SOURCESEAL_S3_SECRET_KEY`	—	S3 secret key for SBOM storage
`SOURCESEAL_TRUST_PROXY`	—	Set to true to trust X-Forwarded-For for client IP detection

Docker Compose

Variable	Default	Description
`POSTGRES_DB`	`sourceseal`	PostgreSQL database name
`POSTGRES_USER`	`sourceseal`	PostgreSQL username
`POSTGRES_PASSWORD`	`sourceseal-dev`	PostgreSQL password. Change in production.
`MINIO_ROOT_USER`	`minioadmin`	MinIO root username. Change in production.
`MINIO_ROOT_PASSWORD`	`minioadmin`	MinIO root password. Change in production.
`S3_BUCKET`	`sourceseal-artifacts`	S3 bucket name for artifact/SBOM storage
`SERVER_PORT`	`8080`	API server listen port
`LOG_LEVEL`	`info`	Logging verbosity
`FABRIC_CA_ADMIN`	`admin`	Fabric CA bootstrap admin username. Change in production.
`FABRIC_CA_ADMIN_PASSWORD`	`adminpw`	Fabric CA bootstrap admin password. Change in production.
`COUCHDB_USER`	`admin`	CouchDB username. Change in production.
`COUCHDB_PASSWORD`	`adminpw`	CouchDB password. Change in production.

Fabric Network Setup Script

Variable	Default	Description
`FABRIC_VERSION`	`2.5.6`	Hyperledger Fabric version to download
`CA_VERSION`	`1.5.9`	Fabric CA version to download
`CHANNEL_NAME`	`sourceseal-channel`	Fabric channel name
`CC_NAME`	`sourceseal-cc`	Chaincode name
`CC_VERSION`	`1.0`	Chaincode version
`CC_SEQUENCE`	`1`	Chaincode lifecycle sequence number