Quick Start

Get Surface Security running locally for evaluation or development using Docker Compose.

Prerequisites

• Docker Desktop with Docker Compose
• Node.js 22+ (for frontend development)
• Go 1.25+ (for backend development)

1. Clone and Start Infrastructure

cd Surface-Security
docker compose up -d

This starts the following services:

Service	Host Port	Purpose
PostgreSQL	5432	Transactional database
ClickHouse	8123 (HTTP), 9000 (Native)	Analytics and event storage
Redpanda	9092	Event streaming
Redpanda Console	8181	Streaming admin UI
MinIO	9500 (API), 9501 (Console)	Object storage (screenshots)
Envoy Gateway	3000	mTLS gateway for extensions
Grafana	3001	Observability dashboards
Tempo	3200	Distributed tracing
OpenTelemetry Collector	4317, 4318	Telemetry collection

2. Start Backend API

cd backend
go run ./cmd/api

The backend API runs on http://localhost:8090.

3. Start Frontend Dashboard

cd frontend
npm install
npm run dev

The frontend dashboard runs on http://localhost:3000.

4. Log In to the Dashboard

Open http://localhost:3000 in your browser. Complete the setup wizard on first launch to create your admin account.

5. Install the Browser Extension (Development)

1. Build the extension:

   cd extension
   npm install
   npm run build

2. Load the extension in Chrome:

   • Navigate to chrome://extensions/
   • Enable Developer mode
   • Click Load unpacked
   • Select the extension/dist folder

3. Configure the extension:

   • Click the Surface Security extension icon in the browser toolbar
   • Navigate to Onboarding in the dashboard (/dashboard/onboarding) to generate an enrollment token
   • Enter the enrollment token in the extension popup and click Enroll Device

6. Verify Everything Is Working

1. Browse to a few websites from the enrolled browser
2. Return to the Surface Security dashboard
3. Check the Dashboard page for incoming navigation events
4. Check the Alerts page for any detected security issues

Service Consoles

Console	URL	Credentials
Dashboard	http://localhost:3000	Set during first-boot wizard
Redpanda Console	http://localhost:8181	(none)
MinIO Console	http://localhost:9501	surfacesec / surfacesec_minio_password
Grafana	http://localhost:3001	admin / admin

Next Steps

• Cloud Onboarding Guide -- connect your identity provider and deploy extensions at scale
• On-Premises Onboarding Guide -- set up a physical appliance
• Hardware Sizing -- choose the right hardware for your endpoint count
• Docker Compose Deployment -- production single-node deployment
• Kubernetes Deployment -- production cluster deployment