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

Documentation Index

​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