Self-Hosted Quickstart — HenKaiPan ASPM

This guide walks you through deploying your own self-hosted HenKaiPan ASPM instance using Docker Compose.

Prerequisites

Disk note: Scanner images total ~6 GB, plus application images and PostgreSQL data.

Quickstart (one-liner)

# Clone and run the installer
git clone https://github.com/Dyallab/HenKaiPan-self-hosted.git
cd HenKaiPan-self-hosted
./install.sh

# Start the stack
docker compose up -d

# Open http://localhost:8080
# Login with admin / <password set during install>

The install.sh script:

• Checks prerequisites (Docker, Compose, architecture)
• Generates secure secrets (JWT_SECRET, SECRET_ENCRYPTION_KEY)
• Prompts for admin password
• Creates .env from template
• Prints next steps

Manual Setup

If you prefer to configure everything by hand:

git clone https://github.com/Dyallab/HenKaiPan-self-hosted.git
cd HenKaiPan-self-hosted

# Create environment file
cp .env.example .env

# Edit .env — set these required variables:
#   DATABASE_URL           PostgreSQL connection string
#   JWT_SECRET             Auth token signing key
#   SECRET_ENCRYPTION_KEY  Encryption key for stored secrets
#   ADMIN_PASS             Default admin password

# Start all services
docker compose up -d

# Check status
docker compose ps

Required Environment Variables

Security: Use strong, unique values for JWT_SECRET and SECRET_ENCRYPTION_KEY. Treat .env as a sensitive file — never commit it.

First Login

1. Open http://localhost:8080
2. Sign in with admin / the password you configured
3. The dashboard loads with an onboarding wizard:
   • Step 1: Create your first project
   • Step 2: Connect a repository (or configure a manual project)
   • Step 3: Run your first scan

Services Architecture

Once running, the stack starts these containers:

The API is a single binary that serves both REST endpoints and the frontend (Astro UI is compiled and embedded using Go's embed package). All traffic goes through port 8080. In production, you typically only expose port 8080 (or 443 behind a reverse proxy).

Docker Socket (Required)

The worker container mounts /var/run/docker.sock to execute security scanners in isolated containers. This is required for scan execution — without it, the worker cannot run any scanners.

# From docker-compose.yml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock

License Key

HenKaiPan runs in free mode without a license key — no time limit, no feature degradation for core functionality.

Free Tier (no key needed)

• Unlimited projects and users
• All scanners: SAST (Semgrep), SCA (Trivy), Secrets (Gitleaks), IaC (Checkov), Containers (Trivy, Nuclei)
• Findings triage, SLA tracking, vulnerability inventory
• Webhooks
• Dashboard, reports, knowledge base

Paid Features (license key required)

• Scan scheduling (cron-based)
• Policies & auto-triage
• Compliance frameworks (SOC 2, ISO 27001, PCI-DSS)
• AI remediation & finding validation
• Integrations (Jira, GitHub, Slack)
• Audit log
• Teams & role-based access

For a license key, contact sales@dyallab.com.ar.

See self-hosted-licensing.md for detailed setup.

Updating

# Pull latest images
docker compose pull

# Recreate containers with new images
docker compose up -d

# Verify
docker compose ps

Migrations run automatically on API startup. Check the API logs to confirm:

docker compose logs api | grep migration

Production Checklist

Before exposing your instance to the internet, verify these:

• HTTPS — Configure a reverse proxy (nginx, Caddy, Traefik) with TLS
• COOKIE_SECURE=true — Set in .env so cookies are only sent over HTTPS
• Strong secrets — JWT_SECRET, SECRET_ENCRYPTION_KEY are unique and random
• Database backups — Configure automated backups (see self-hosted-backup.md)
• Email (SMTP) — Configure notifications for alerts and digests
• Resource limits — Set Docker container memory/CPU limits in production
• Monitoring — Health check at /api/health, Prometheus metrics at :9090/metrics

Reverse Proxy Example (Caddy)

aspm.yourcompany.com {
    reverse_proxy localhost:8080
}

Reverse Proxy Example (nginx)

server {
    listen 443 ssl;
    server_name aspm.yourcompany.com;

    ssl_certificate     /etc/ssl/certs/aspm.crt;
    ssl_certificate_key /etc/ssl/private/aspm.key;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Troubleshooting

Containers exit immediately

Check logs:

docker compose logs api
docker compose logs worker

Common causes:

• Missing .env file or required env vars
• PostgreSQL not ready when API starts (restart policy handles this, but first start may take a moment)
• Port conflict on 8080, 5432, or 6379

Scans fail to start

Verify Docker socket is mounted:

docker compose exec worker docker ps

If this fails, restart with the socket mounted:

# Ensure docker-compose.yml has the volume
docker compose down
docker compose up -d

"Cannot connect to Redis"

Check Redis is running and REDIS_ADDR is correct:

docker compose ps redis
# Default: localhost:6379

Reset everything

docker compose down -v   # Warning: destroys all data
docker compose up -d

File Reference