Installation & Configuration — Claw GRC Docs

Deployment Options

Claw GRC supports two deployment modes. For most organizations, the managed SaaS at clawgrc.com is the fastest path to a live compliance posture. Self-hosted is available for organizations with strict data residency requirements or FedRAMP/IL compliance needs.

Mode	Description	Best For
Managed SaaS	Hosted at clawgrc.com. Zero infra overhead. Automatic updates and backups.	Recommended
Self-Hosted (Docker)	Run via Docker Compose on your own servers. Full control over data.	Self-Hosted
Cloud Run (GCP)	Managed containers on Google Cloud Run. Scales to zero between scans.	Cloud

Self-Hosted: Docker Compose

The Docker Compose setup runs all five services — API Gateway, Compliance Engine, Security Engine, Agent Protocol, and the Next.js frontend — plus PostgreSQL, Redis, and optional GCP emulators.

Prerequisites

Docker 24+ and Docker Compose v2.20+
4 CPU cores, 8 GB RAM minimum (16 GB recommended for production)
A Firebase project for authentication
PostgreSQL 16 (included in Compose, or use Cloud SQL / RDS)

1. Clone the repository

git clone https://github.com/ClawGRC/ClawGRC.git
cd ClawGRC

2. Configure environment variables

Copy the example environment file and fill in your values. The minimum required variables are marked with *.

.envbash

# ─── Database ─────────────────────────────────────────────────────────────
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=claw
POSTGRES_PASSWORD=clawgrc_dev_password
POSTGRES_DB=clawgrc
DATABASE_URL=postgres://claw:clawgrc_dev_password@localhost:5432/clawgrc?sslmode=disable

# ─── Redis ────────────────────────────────────────────────────────────────
REDIS_URL=redis://localhost:6379

# ─── GCP ──────────────────────────────────────────────────────────────────
GCP_PROJECT_ID=claw-grc-dev

# ─── Firebase Auth ────────────────────────────────────────────────────────
FIREBASE_PROJECT_ID=claw-grc-dev          # *
FIREBASE_API_KEY=your-firebase-api-key    # *

# ─── Frontend ─────────────────────────────────────────────────────────────
NEXT_PUBLIC_API_URL=http://localhost:8080

# ─── Environment ──────────────────────────────────────────────────────────
ENVIRONMENT=development                   # development | production

# ─── Optional: Evidence Storage ───────────────────────────────────────────
EVIDENCE_BUCKET=clawgrc-evidence-dev

# ─── Optional: Claw GRC API Key (for MCP server) ─────────────────────────
CLAW_GRC_API_KEY=cgrc_live_...

Never commit .env to git

The .env file contains secrets. It is already in .gitignore. In production, use GCP Secret Manager or AWS Secrets Manager to inject secrets at runtime.

3. Start all services

# Start all services in the background
make dev-d

# Or start in the foreground (shows all logs)
make dev

# Check service status
docker compose ps

4. Run database migrations and seed

# Apply all migrations (creates 20+ tables)
make migrate

# Seed compliance frameworks and controls
# This loads 11 frameworks and 1,026 controls
make seed

Existing database?

If you are migrating an existing database that was set up before golang-migrate, run make migrate-bootstrap first to initialize version tracking.

Seed data is idempotent

The seed command uses ON CONFLICT DO UPDATE on all inserts. It is safe to re-run without duplicating data.

Service ports

Service	Local Port	Purpose
web (Next.js)	Port 3000	Frontend
api-gateway	Port 8080 — Auth, routing, rate limiting	Go
compliance-engine	Port 8081 — Frameworks, controls, evidence	Go
security-engine	Port 8082 — Assessments, findings, scans	Python
agent-protocol	Port 8083 — Agent registry, trust, MCP	Python
postgres	Port 5433 — PostgreSQL 16 with RLS	DB
redis	Port 6379 — In-memory cache and session store	Redis

Production: Google Cloud Run

The recommended production deployment uses Google Cloud Run, Cloud SQL for PostgreSQL, GCS for evidence file storage, and Secret Manager for secrets.

Docker image builds

All images must be built for linux/amd64 to run on Cloud Run. Use the --provenance=false flag to avoid multi-platform manifest issues.

# Build each service image
docker build --platform linux/amd64 --provenance=false   -t gcr.io/YOUR_PROJECT/claw-grc-api-gateway:latest   apps/api-gateway/

docker build --platform linux/amd64 --provenance=false   -t gcr.io/YOUR_PROJECT/claw-grc-compliance-engine:latest   apps/compliance-engine/

# Push to Container Registry
docker push gcr.io/YOUR_PROJECT/claw-grc-api-gateway:latest
docker push gcr.io/YOUR_PROJECT/claw-grc-compliance-engine:latest

Cloud Run deployment

gcloud run deploy claw-grc-api-gateway   --image gcr.io/YOUR_PROJECT/claw-grc-api-gateway:latest   --platform managed   --region us-central1   --allow-unauthenticated   --set-secrets POSTGRES_PASSWORD=claw-postgres-password:latest   --set-secrets JWT_SECRET=claw-jwt-secret:latest   --set-env-vars ENVIRONMENT=production

Use /readyz not /healthz for health checks

Cloud Run intercepts /healthz at the load balancer level. All Claw GRC services expose /readyz as the health check endpoint. Configure your Cloud Run health checks to use /readyz.

First-Time Configuration Checklist

After deployment, complete these configuration steps before inviting your team:

Set organization name and logo

Dashboard → Settings → Organization

Invite team members

Dashboard → Settings → Team Members. Assign Admin, Compliance, or Viewer roles

Activate your primary framework

Dashboard → Frameworks → [Framework Name] → Activate

Assign control owners

Frameworks → Controls → bulk-assign team members to control categories

Connect your first integration

Dashboard → Integrations → select GitHub, AWS, or Okta

Configure evidence freshness thresholds

Settings → Evidence → set days-until-stale per evidence type

Run baseline security scan

Dashboard → Scans → Run Scan → Dependency + Secrets

Review generated tickets

Dashboard → Tickets — scan findings automatically create remediation tickets

Enable Slack notifications

Settings → Notifications → Slack → paste webhook URL

Generate first report

Reports → SOC 2 Readiness → Generate PDF

Environment Variables Reference

Variable	Description	Required
DATABASE_URL	Full PostgreSQL connection string used by all services	Required
REDIS_URL	Redis connection string for caching and sessions	Required
FIREBASE_PROJECT_ID	Your Firebase project ID for authentication	Required
FIREBASE_API_KEY	Firebase API key for client-side authentication	Required
ENVIRONMENT	development (bypasses auth) or production	Required
EVIDENCE_BUCKET	Cloud Storage bucket for evidence file uploads	Optional
CLAW_GRC_API_KEY	API key for MCP server authentication	Optional
SLACK_WEBHOOK_URL	Slack incoming webhook for notifications	Optional

Development mode bypasses authentication

When ENVIRONMENT=development, the API Gateway operates in pass-through mode and all requests are treated as authenticated. Never use this in production.