Local Deployment Guide

Deploy OSCAL Hub on your local machine or VM for testing and development.

Version: 1.0.0 · Updated: October 26, 2025

Overview

This guide shows you how to run the full OSCAL Hub stack locally on your laptop or a VM. Perfect for testing, development, training, offline use, and demos.

What Gets Installed

• Frontend — Next.js web application (port 3010 in dev, 3000 in production Docker)
• Backend API — Spring Boot REST API (port 8090 in dev, 8080 in production Docker)
• PostgreSQL Database — Production-grade database (port 5432)
• pgAdmin — Database management UI (port 5050)

All running in Docker containers for easy setup and isolation.

Quick Start (5 Minutes)

Option 1: Automated Script (Easiest)

# 1. Clone the repository
git clone https://github.com/RegScale/oscal-hub.git
cd oscal-cli

# 2. Run the development startup script (from project root)
./dev.sh

# 3. Open your browser
open http://localhost:3010

The script will:

• Check prerequisites
• Start PostgreSQL via Docker
• Start the backend (Spring Boot)
• Start the frontend (Next.js dev server)

Total time: 5–10 minutes (longer on first run)

Option 2: Manual Docker Compose

# 1. Clone and build
git clone https://github.com/RegScale/oscal-hub.git
cd oscal-cli

# 2. Build backend
cd back-end
mvn clean package -DskipTests
cd ..

# 3. Build frontend
cd front-end
npm ci
npm run build
cd ..

# 4. Start with Docker Compose
docker-compose up -d

# 5. Open browser
open http://localhost:3000

Option 3: Development Mode (No Docker for app)

# 1. Clone repository
git clone https://github.com/RegScale/oscal-hub.git
cd oscal-cli

# 2. Start PostgreSQL (Docker only for database)
docker-compose -f docker-compose-postgres.yml up -d

# 3. Start backend (in one terminal)
cd back-end
mvn spring-boot:run -Dspring.profiles.active=dev

# 4. Start frontend (in another terminal)
cd front-end
npm install
npm run dev

# Access:
# - Frontend: http://localhost:3010
# - Backend API: http://localhost:8090

Prerequisites

Required Software

1. Docker Desktop (version 20.10+)

• macOS: Download Docker Desktop for Mac
• Windows: Download Docker Desktop for Windows
• Linux: Download Docker Desktop for Linux

2. Git

• macOS: Already installed or via Homebrew: brew install git
• Windows: Download Git for Windows
• Linux: sudo apt-get install git (Ubuntu/Debian)

System Requirements

Verify Prerequisites

# Check Docker
docker --version
# Expected: Docker version 20.10.0 or higher

# Check Docker Compose
docker-compose --version
# Expected: Docker Compose version 2.x or higher

# Check if Docker is running
docker info
# Should show Docker engine information

Using the Application

First-Time Setup

1. Open your browser

   Navigate to http://localhost:3010 (dev mode) or http://localhost:3000 (Docker Compose).

2. Register an account

   Click Register or Sign Up.

3. Fill in your details

   Password must be at least 10 characters with uppercase, lowercase, digit, and special character.

4. Log in

   Sign in with your new credentials.

5. Start validating

   Upload and validate OSCAL documents.

Access Points (Dev Mode)

Management Commands

Using the dev.sh Script

# Start all services (PostgreSQL via Docker, backend, frontend)
./dev.sh

# Stop all servers
./stop.sh

Using Docker Compose (Full Stack)

# View running containers
docker-compose ps

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f oscal-ux
docker-compose logs -f postgres

# Stop application
docker-compose stop

# Start application
docker-compose start

# Restart specific service
docker-compose restart oscal-ux

# Stop and remove containers
docker-compose down

# Stop and remove containers + volumes (deletes data!)
docker-compose down -v

Troubleshooting

Docker is not running

Symptom: Script fails with "Docker daemon is not running"

Solution:

1. Start Docker Desktop application
2. Wait for Docker to fully start (icon in system tray)
3. Verify with: docker info
4. Run the script again: ./dev.sh

Port already in use

Symptom: Error: Port 3010 or 8090 is already in use

# Find what's using port 3010
lsof -i :3010
# Kill the process
kill -9 <PID>

# Or for port 8090
lsof -i :8090
kill -9 <PID>

Container keeps restarting

Symptom: docker-compose ps shows "Restarting" status

# View logs to see error
docker-compose logs oscal-ux

# Common causes:
# 1. Database not ready - wait 30 seconds and check again
# 2. Environment variable missing - check docker-compose.yml
# 3. Port conflict - see "Port already in use" above

# Try restart
docker-compose restart

Frontend shows "Cannot connect to API"

Symptom: Frontend loads but shows connection error

# 1. Check if backend is running
curl http://localhost:8090/api/health

# 2. If not responding, check logs
docker-compose logs oscal-ux

# 3. Common fixes:
# - Wait longer (backend takes 30-60 seconds to start)
# - Check if port 8090 is accessible
# - Restart: docker-compose restart oscal-ux

Advanced Configuration

Custom Configuration

Create a .env file in the project root:

# Database
DB_NAME=oscal_dev
DB_USER=oscal_user
DB_PASSWORD=oscal_dev_password

# Application
JWT_SECRET=dev-secret-key-at-least-32-characters-long
CORS_ALLOWED_ORIGINS=http://localhost:3010,http://localhost:3001

# Features
SPRING_PROFILES_ACTIVE=dev
SWAGGER_ENABLED=true
RATE_LIMIT_ENABLED=false

Comparison: Local vs Azure Deployment

Next Steps

After successful local deployment:

• Read the User Guide
• Try validating OSCAL documents via the web interface
• Explore the API at http://localhost:8090/swagger-ui.html
• Learn about Azure deployment for production

Additional Resources

• Docker Documentation
• Docker Compose Documentation
• API Automation Guide
• NIST OSCAL Documentation