Local Installation and Configuration
SecuScan — Local Installation and Configuration
Local Installation and Configuration
<h2 id="bkmrk-local-installation-a">Local Installation and Configuration — SecuScan v0.28.0</h2>
<h3 id="bkmrk-prerequisites">Prerequisites</h3> <table id="bkmrk-componentminimum-ver"> <thead><tr><th>Component</th><th>Minimum Version</th><th>Usage</th></tr></thead> <tbody> <tr><td>Go</td><td>1.23+</td><td>Backend API, Worker, Codeworker, Pentest Worker</td></tr> <tr><td>Node.js</td><td>18+</td><td>Frontend Next.js 14</td></tr> <tr><td>PostgreSQL</td><td>15+</td><td>Multi-tenant database (RLS)</td></tr> <tr><td>Redis</td><td>7+</td><td>Cache, job queue, rate limiting</td></tr> <tr><td>Docker & Docker Compose</td><td>20+</td><td>Local infrastructure and deployment images</td></tr> <tr><td>Make</td><td>GNU Make</td><td>Build and dev commands</td></tr> </tbody> </table>
<h3 id="bkmrk-project-structure">Project Structure</h3> <pre id="bkmrk-secuscan%2F-%2B---secusc"><code>SecuScan/ +-- secuscan-api/ # Go Backend API (monorepo) | +-- cmd/api/ # API entry point (port 8080) | +-- cmd/worker/ # Worker entry point (22 network tools) | +-- cmd/codeworker/ # Codeworker entry point (103 functions) | +-- cmd/pentest-worker/ # Pentest Worker entry point (Temporal) | +-- internal/ # Internal code | | +-- api/handlers/ # 20+ HTTP handlers | | +-- api/middleware/ # Auth, CORS, Rate Limit, Logging, Tenant | | +-- config/ # YAML + env vars configuration | | +-- domain/models/ # Domain models (30+ structs) | | +-- repository/ # PostgreSQL + Redis repos | | +-- services/ # Business logic | | +-- scanner/ # 22 network scanning tools | | +-- migrations/ # 26 embedded SQL migrations (go:embed) | +-- pkg/ # Shared packages (validator, ai, crypto) | +-- migrations/ # SQL source files | +-- Dockerfile* # 5 Dockerfiles (backend, worker, codeworker, pentest-*) +-- secuscan-web/ # Next.js 14 Frontend | +-- app/ # Routes (App Router, 59+ routes) | +-- components/ # Reusable React components | +-- hooks/ # Custom hooks (mutations, queries) | +-- messages/ # i18n files (fr.json, en.json) | +-- types/ # TypeScript types +-- secuscan-agent/ # Go CLI Agent (client deployment) +-- secuscan-pentest-agent/ # Pentest Agent (Claude AI) +-- deploy/k8s/ # Kubernetes manifests (secuscan.yaml) +-- docker-compose.yml # Local infrastructure (PostgreSQL + Redis) +-- Makefile # Build and dev commands </code></pre>
<h3 id="bkmrk-quick-start">Quick Start</h3>
<h4 id="bkmrk-1.-clone-the-project">1. Clone the project</h4> <pre id="bkmrk-cd-%2Fhome%2Fubuntu%2Fproj"><code class="language-bash">cd /home/ubuntu/projects git clone https://github.com/secuaas/SecuScan.git cd SecuScan</code></pre>
<h4 id="bkmrk-2.-start-local-infra">2. Start local infrastructure</h4> <pre id="bkmrk-%23-start-postgresql-a"><code class="language-bash"># Start PostgreSQL and Redis via Docker Compose make docker-up</code></pre> <p id="bkmrk-this-starts%3A">This starts:</p> <ul id="bkmrk-postgresql-15-on-por"> <li>PostgreSQL 15 on port 5432 (user: secuscan, password: secuscan, db: secuscan)</li> <li>Redis 7 on port 6379</li> </ul>
<h4 id="bkmrk-3.-configure-environ">3. Configure environment variables</h4> <pre id="bkmrk-cd-secuscan-api-cp-."><code class="language-bash">cd secuscan-api cp .env.example .env
Edit .env with appropriate values</code></pre>
<p id="bkmrk-essential-variables%3A">Essential variables:</p> <pre id="bkmrk-%23-database-db_host%3Dl"><code class="language-bash"># Database DB_HOST=localhost DB_PORT=5432 DB_NAME=secuscan DB_USER=secuscan DB_PASSWORD=secuscan
Redis
REDIS_HOST=localhost REDIS_PORT=6379
JWT
JWT_SECRET=your-local-jwt-secret
Optional - AI (Claude)
CLAUDE_API_KEY=sk-ant-... CLAUDE_MODEL=claude-sonnet-4-5-20250929 CODE_SCAN_ENABLE_AI=true
Optional - SSO
SSO_ENABLED=false
Optional - Stripe
STRIPE_SECRET_KEY=sk_test_... STRIPE_WEBHOOK_SECRET=whsec_...</code></pre>
<h4 id="bkmrk-4.-start-the-backend">4. Start the backend API</h4> <pre id="bkmrk-%23-install-go-depende"><code class="language-bash"># Install Go dependencies and compile make api-install
Start the API (port 8080)
make api-dev</code></pre> <p id="bkmrk-the-26-sql-migration">The 26 SQL migrations run automatically on startup. RLS (Row Level Security) is configured for each table.</p>
<h4 id="bkmrk-5.-start-the-worker-">5. Start the worker (network scans)</h4> <pre id="bkmrk-%23-in-another-termina"><code class="language-bash"># In another terminal make worker-dev</code></pre>
<h4 id="bkmrk-6.-start-the-codewor">6. Start the codeworker (code scans)</h4> <pre id="bkmrk-%23-in-another-termina-1"><code class="language-bash"># In another terminal (optional, for code scanning) make codeworker-dev</code></pre>
<h4 id="bkmrk-7.-start-the-fronten">7. Start the frontend</h4> <pre id="bkmrk-%23-install-npm-depend"><code class="language-bash"># Install npm dependencies make web-install
Start the frontend (port 3000)
make web-dev</code></pre>
<h4 id="bkmrk-8.-verify">8. Verify</h4> <pre id="bkmrk-%23-api-health-check-c"><code class="language-bash"># API health check curl http://localhost:8080/health
Frontend
open http://localhost:3000</code></pre>
<h3 id="bkmrk-advanced-configurati">Advanced Configuration</h3> <p id="bkmrk-configuration-suppor">Configuration supports two sources (priority: environment variables > YAML file):</p>
<h4 id="bkmrk-yaml-file-%28config.ya">YAML File (config.yaml)</h4> <pre id="bkmrk-server%3A-host%3A-0.0.0."><code class="language-yaml">server: host: 0.0.0.0 port: 8080 environment: development
database: host: localhost port: 5432 database: secuscan user: secuscan password: secuscan max_connections: 25 min_connections: 5
redis: host: localhost port: 6379
jwt: secret: dev-secret access_expiry: 60m refresh_expiry: 168h issuer: secuscan
temporal: host: localhost:7233 namespace: default
sso: enabled: false zitadel_issuer: https://auth.secuaas.com
cors: allowed_origins:
<h3 id="bkmrk-make-commands">Make Commands</h3> <table id="bkmrk-commanddescription-m"> <thead><tr><th>Command</th><th>Description</th></tr></thead> <tbody> <tr><td><code>make docker-up</code></td><td>Start PostgreSQL + Redis</td></tr> <tr><td><code>make docker-down</code></td><td>Stop containers</td></tr> <tr><td><code>make api-install</code></td><td>Install Go dependencies</td></tr> <tr><td><code>make api-dev</code></td><td>Run API in dev mode</td></tr> <tr><td><code>make api-build</code></td><td>Compile API binary</td></tr> <tr><td><code>make api-test</code></td><td>Run Go tests</td></tr> <tr><td><code>make worker-dev</code></td><td>Run worker in dev mode</td></tr> <tr><td><code>make codeworker-dev</code></td><td>Run codeworker in dev mode</td></tr> <tr><td><code>make web-install</code></td><td>Install npm dependencies</td></tr> <tr><td><code>make web-dev</code></td><td>Run frontend in dev mode</td></tr> <tr><td><code>make web-build</code></td><td>Production Next.js build</td></tr> <tr><td><code>make web-test</code></td><td>Run vitest tests (121 tests)</td></tr> <tr><td><code>make build</code></td><td>Full build (api + worker + codeworker + web)</td></tr> <tr><td><code>make test</code></td><td>All tests (Go + vitest)</td></tr> <tr><td><code>make clean</code></td><td>Clean build artifacts</td></tr> </tbody> </table>
<h3 id="bkmrk-deployment-with-secu">Deployment with secuops</h3> <pre id="bkmrk-%23-complete-project-t"><code class="language-bash"># Complete project topology secuops deploy-info --project=secuscan
Build all 6 Docker images and push to Harbor
secuops build --app=secuscan --env=k8s-dev
Deploy to Kubernetes
secuops deploy --app=secuscan --env=k8s-dev
Check status
secuops status --app=secuscan --env=k8s-dev
View logs
secuops logs --app=secuscan --env=k8s-dev</code></pre>
<h3 id="bkmrk-common-troubleshooti">Common Troubleshooting</h3> <table id="bkmrk-issuecausesolution-p"> <thead><tr><th>Issue</th><th>Cause</th><th>Solution</th></tr></thead> <tbody> <tr><td>Pod CrashLoopBackOff</td><td>Missing secrets or migration error</td><td>Check logs with <code>secuops logs</code></td></tr> <tr><td>PostgreSQL auth failure (SASL)</td><td>Mismatch between K8s secret and PVC</td><td><code>ALTER USER secuscan WITH PASSWORD '...'</code></td></tr> <tr><td>ImagePullBackOff</td><td>Harbor secret missing from namespace</td><td>Verify registry secret exists</td></tr> <tr><td>CORS errors</td><td>Unauthorized origin</td><td>Add origin to CORS_ALLOWED_ORIGINS</td></tr> <tr><td>AI features inactive</td><td>Missing Claude API key</td><td>Configure CLAUDE_API_KEY and CODE_SCAN_ENABLE_AI=true</td></tr> </tbody> </table>