Skip to content

Installation

Jump to bottom
cyclonite69 edited this page Feb 7, 2026 · 1 revision

Installation Guide

Complete setup instructions for ShadowCheck development and production environments.

Prerequisites

Required Software

Software Version Purpose
Node.js 20+ Runtime environment
PostgreSQL 18+ Database with PostGIS extension
Docker 20.10+ Containerization (optional but recommended)
Git 2.30+ Version control

System Requirements

Minimum:

  • CPU: 2 cores
  • RAM: 4 GB
  • Storage: 20 GB SSD

Recommended:

  • CPU: 4 cores
  • RAM: 8 GB
  • Storage: 50 GB SSD

Quick Installation

1. Clone Repository

git clone https://github.com/cyclonite69/shadowcheck-static.git
cd shadowcheck-static

2. Install Node.js Dependencies

npm install

3. Set Up PostgreSQL

Option A: Docker (Recommended)

# Start PostgreSQL with PostGIS
docker-compose up -d postgres

# Verify it's running
docker ps | grep shadowcheck_postgres

Option B: Local PostgreSQL

-- Create database users
CREATE ROLE shadowcheck_user WITH LOGIN PASSWORD 'your_password';
CREATE ROLE shadowcheck_admin WITH LOGIN PASSWORD 'admin_password';

-- Create database
CREATE DATABASE shadowcheck_db OWNER shadowcheck_admin;
\c shadowcheck_db
CREATE EXTENSION postgis;

4. Configure Environment

# Copy example environment file
cp .env.example .env

# Edit with your settings
nano .env

Essential environment variables:

# Database
DB_USER=shadowcheck_user
DB_HOST=localhost
DB_NAME=shadowcheck_db
DB_PORT=5432

# Server
PORT=3001
NODE_ENV=development

# Frontend
MAPBOX_TOKEN=pk.your_mapbox_token_here

5. Set Secrets

# Set database password in keyring
node scripts/set-secret.js db_password "your_password"

# Set admin password
node scripts/set-secret.js db_admin_password "admin_password"

# Set Mapbox token
node scripts/set-secret.js mapbox_token "pk.your_token"

6. Run Migrations

# Apply security migration
psql -U shadowcheck_admin -d shadowcheck_db -f sql/migrations/20260129_implement_db_security.sql

7. Start Development Server

# Terminal 1: Start backend
npm run dev

# Terminal 2: Start frontend
npm run dev:frontend

Access the application:

DevContainer Setup (Recommended)

Prerequisites

  • Docker Desktop
  • VS Code with Dev Containers extension

Steps

  1. Open in DevContainer (VS Code will prompt)
  2. Wait for container build (includes Node.js 20, PostgreSQL 18, PostGIS)
  3. Start developing: 
    npm run dev          # Backend
npm run dev:frontend # Frontend

Production Deployment

Local Development

# Configure environment
cp .env.example .env
nano .env

# Start infrastructure
docker-compose up -d

Home Lab Deployment

# Automated setup (detects RAM, configures PostgreSQL)
./deploy/homelab/scripts/setup.sh

# Manual setup
docker-compose -f docker/infrastructure/docker-compose.postgres.yml up -d
docker-compose up -d

See deploy/homelab/README.md for hardware requirements.

AWS Production

# Launch Spot instance with persistent storage
./deploy/aws/scripts/launch-shadowcheck-spot.sh

# Connect via SSM
aws ssm start-session --target i-INSTANCE_ID --region us-east-1

See deploy/aws/README.md for AWS infrastructure details.

Security Setup

Password Rotation

# Rotate database password (auto-detects environment)
./scripts/rotate-db-password.sh

Recommended schedule: Every 60-90 days

See deploy/aws/docs/PASSWORD_ROTATION.md for detailed procedures.

Verification

# Test API
curl http://localhost:3001/api/dashboard-metrics

# Run tests
npm test

Next Steps

Clone this wiki locally