Installation

This guide covers the complete installation process for SGIVU, including prerequisites, environment setup, and configuration.

System Requirements

Hardware Requirements

CPU: 4+ cores recommended
RAM: Minimum 8GB, 16GB recommended
Storage: 20GB+ free disk space
Network: Stable internet connection for pulling Docker images

Software Requirements

Operating System: Linux, macOS, or Windows with WSL2
Docker: Version 20.10 or later
Docker Compose: Version 2.0 or later
Git: Version 2.30 or later

Installation Methods

# Clone the repository
git clone https://github.com/your-org/sgivu.git
cd sgivu/infra/compose/sgivu-docker-compose

# Create environment file
cp .env.dev.example .env.dev

# Start the stack
chmod +x run.bash
./run.bash --dev

Step-by-Step Installation

Install Docker and Docker Compose

Linux

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to the docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Verify installation
docker --version
docker compose version

macOS

# Install Docker Desktop for Mac
brew install --cask docker

# Start Docker Desktop and verify
docker --version
docker compose version

Windows (WSL2)

Install WSL2: https://docs.microsoft.com/en-us/windows/wsl/install
Install Docker Desktop for Windows
Enable WSL2 integration in Docker Desktop settings
Verify installation in WSL2 terminal:

docker --version
docker compose version

Clone the SGIVU repository

git clone https://github.com/your-org/sgivu.git
cd sgivu

Verify the repository structure:

ls -la
# You should see:
# - apps/          (backend, frontend, ML services)
# - infra/         (Docker Compose, Nginx configs)
# - docs/          (documentation)
# - scripts/       (utility scripts)

Prepare the Config Repository

SGIVU uses centralized configuration stored in a separate Git repository. For development, you can use the native profile to load configs from the local filesystem.

# Clone the config repository (if using Git profile)
git clone https://github.com/stevenrq/sgivu-config-repo.git

# Or create a local config directory structure
mkdir -p sgivu-config-repo
cd sgivu-config-repo
# Add your configuration YAML files here

The Docker Compose dev setup uses the native profile and mounts the config directory automatically.

Configure Environment Variables

Navigate to the Docker Compose directory:

cd infra/compose/sgivu-docker-compose

For development:

cp .env.dev.example .env.dev

For production:

cp .env.example .env

Edit the environment file with your preferred editor:

nano .env.dev
# or
vim .env.dev

Key variables to configure (see Configuration for details):

SERVICE_INTERNAL_SECRET_KEY - Secret for service-to-service communication
REDIS_PASSWORD - Redis authentication password
POSTGRES_PASSWORD - PostgreSQL password
MYSQL_ROOT_PASSWORD - MySQL root password
JWT_KEYSTORE_PASSWORD - JWT keystore password
SGIVU_GATEWAY_SECRET - OAuth2 client secret

Generate JWT Keystore (Production Only)

For production deployments, generate a custom JWT keystore:

keytool -genkeypair -alias sgivu-jwt \
  -keyalg RSA -keysize 2048 \
  -storetype JKS -keystore keystore.jks \
  -validity 3650 \
  -storepass YOUR_KEYSTORE_PASSWORD \
  -keypass YOUR_KEY_PASSWORD \
  -dname "CN=SGIVU Auth, OU=Security, O=SGIVU, L=City, ST=State, C=US"

Place the keystore in the auth service resources directory:

cp keystore.jks apps/backend/sgivu-auth/src/main/resources/

Update the environment variables:

JWT_KEYSTORE_LOCATION=classpath:keystore.jks
JWT_KEYSTORE_PASSWORD=YOUR_KEYSTORE_PASSWORD
JWT_KEY_ALIAS=sgivu-jwt
JWT_KEY_PASSWORD=YOUR_KEY_PASSWORD

Configure AWS S3 (Production Only)

For vehicle image storage, configure AWS S3:

Create an S3 bucket:

aws s3 mb s3://sgivu-vehicle-images --region us-east-1

Create an IAM user with S3 access and generate access keys
Update environment variables:

AWS_ACCESS_KEY=your-access-key
AWS_SECRET_KEY=your-secret-key
AWS_REGION=us-east-1
AWS_VEHICLES_BUCKET=sgivu-vehicle-images
AWS_S3_ALLOWED_ORIGINS=http://your-frontend-domain.com

Configure bucket CORS policy to allow frontend access

Initialize Databases (Optional)

The Docker Compose setup automatically initializes databases. For manual setup:

# PostgreSQL databases
psql -h localhost -U postgres -c "CREATE DATABASE sgivu_auth_db;"
psql -h localhost -U postgres -c "CREATE DATABASE sgivu_user_db;"
psql -h localhost -U postgres -c "CREATE DATABASE sgivu_client_db;"
psql -h localhost -U postgres -c "CREATE DATABASE sgivu_vehicle_db;"
psql -h localhost -U postgres -c "CREATE DATABASE sgivu_purchase_sale_db;"
psql -h localhost -U postgres -c "CREATE DATABASE sgivu_ml_db;"

# MySQL database (for Zipkin)
mysql -h localhost -u root -p -e "CREATE DATABASE sgivu_zipkin_db;"
mysql -h localhost -u root -p -e "CREATE USER 'zipkin'@'%' IDENTIFIED BY 'your-password';"
mysql -h localhost -u root -p -e "GRANT ALL PRIVILEGES ON sgivu_zipkin_db.* TO 'zipkin'@'%';"

Flyway migrations run automatically when services start.

Start the Platform

Launch the complete stack:

chmod +x run.bash

# For development
./run.bash --dev

# For production
./run.bash --prod

Alternatively, use Docker Compose directly:

# Development
docker compose -f docker-compose.dev.yml --env-file .env.dev up -d --build

# Production
docker compose up -d --build

Verify Installation

Check all services are running:

docker compose -f docker-compose.dev.yml ps

Verify Eureka service registry:

curl http://localhost:8761

Check Config Server:

curl http://localhost:8888/actuator/health

Test the Gateway:

curl http://localhost:8080/actuator/health

View logs:

# All services
docker compose -f docker-compose.dev.yml logs -f

# Specific service
docker compose -f docker-compose.dev.yml logs -f sgivu-gateway

Post-Installation Configuration

Configure Nginx (Production)

For production deployments, configure Nginx as the public entry point:

# /etc/nginx/sites-available/sgivu
server {
    listen 80;
    server_name your-domain.com;

    # Auth Server endpoints
    location ~ ^/(login|oauth2|.well-known) {
        proxy_pass http://localhost:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Gateway endpoints
    location ~ ^/(v1|docs|auth/session) {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Frontend (SPA)
    location / {
        # Proxy to S3 or serve from local
        root /var/www/sgivu-frontend/dist;
        try_files $uri $uri/ /index.html;
    }
}

Enable and restart Nginx:

sudo ln -s /etc/nginx/sites-available/sgivu /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Set Up Monitoring

Access Zipkin for distributed tracing:

open http://localhost:9411

Enable Actuator endpoints for monitoring:

curl http://localhost:8080/actuator
curl http://localhost:9000/actuator/health

Troubleshooting

Docker Issues

Problem: Docker daemon not running

sudo systemctl start docker

Problem: Permission denied

sudo usermod -aG docker $USER
newgrp docker

Port Conflicts

Problem: Ports already in use

# Find process using port
lsof -i :8080

# Kill the process or change port mapping in docker-compose

Service Startup Issues

Problem: Config Server not accessible

# Check Config Server logs
docker compose -f docker-compose.dev.yml logs sgivu-config

# Verify SPRING_CLOUD_CONFIG_URI is correct

Problem: Services not registering with Eureka

# Check Eureka is running
curl http://localhost:8761

# Verify EUREKA_URL in .env.dev

Problem: Authentication failures

# Verify JWT keystore configuration
# Check ISSUER_URL matches SGIVU_AUTH_URL
# Ensure SGIVU_GATEWAY_SECRET is consistent

Database Issues

Problem: Database connection failures

# Check PostgreSQL is running
docker compose -f docker-compose.dev.yml ps sgivu-postgres

# Verify credentials in .env.dev
# Check database logs
docker compose -f docker-compose.dev.yml logs sgivu-postgres

Next Steps

Configuration

Learn about all configuration options

Docker Deployment

Understand the Docker architecture

API Reference

Explore the API documentation

Architecture

Understand the system architecture

Overview

Getting Started

Core Features

Infrastructure

Security

Installation

System Requirements

Hardware Requirements

Software Requirements

Installation Methods

Step-by-Step Installation

Linux

macOS

Windows (WSL2)

Post-Installation Configuration

Configure Nginx (Production)

Set Up Monitoring

Troubleshooting

Docker Issues

Port Conflicts

Service Startup Issues

Database Issues

Next Steps

Configuration

Docker Deployment

API Reference

Architecture

Overview

Getting Started

Core Features

Infrastructure

Security

​System Requirements

​Hardware Requirements

​Software Requirements

​Installation Methods

​Step-by-Step Installation

​Linux

​macOS

​Windows (WSL2)

​Post-Installation Configuration

​Configure Nginx (Production)

​Set Up Monitoring

​Troubleshooting

​Docker Issues

​Port Conflicts

​Service Startup Issues

​Database Issues

​Next Steps

Configuration

Docker Deployment

API Reference

Architecture

System Requirements

Hardware Requirements

Software Requirements

Installation Methods

Step-by-Step Installation

Linux

macOS

Windows (WSL2)

Post-Installation Configuration

Configure Nginx (Production)

Set Up Monitoring

Troubleshooting

Docker Issues

Port Conflicts

Service Startup Issues

Database Issues

Next Steps