warehouse13/docs/QUICKSTART.md

Quick Start Guide

Overview

The Test Artifact Data Lake platform provides several ways to run the application depending on your use case:

• Development: Backend services in Docker + Frontend dev server with hot reload
• Production: Complete stack in Docker containers
• Testing: Various rebuild and cleanup options

Prerequisites

• Docker Desktop (Windows/macOS) or Docker + Docker Compose (Linux)
• Node.js 18+ (for development mode)
• npm (for development mode)

Quick Start Options

1. Development Mode (Recommended for Development)

Linux/macOS:

./quickstart.sh                # Backend services only
./dev-start.sh                 # Backend + Frontend dev server

Windows:

.\quickstart.ps1               # Backend services only
.\quickstart.ps1 -FullStack    # Complete stack
.\quickstart.ps1 -Rebuild      # Rebuild containers
.\dev-start.ps1                # Backend + Frontend dev server

URLs:

• Frontend: http://localhost:4200 (with hot reload)
• API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• MinIO Console: http://localhost:9001

2. Production Mode (Complete Stack)

Linux/macOS:

./quickstart.sh --full-stack

Windows:

.\quickstart.ps1 -FullStack

URLs:

• Frontend: http://localhost:80 (production build)
• API: http://localhost:8000
• MinIO Console: http://localhost:9001

3. Force Rebuild (When Code Changes)

Linux/macOS:

./quickstart.sh --rebuild                    # Rebuild backend only
./quickstart.sh --rebuild --full-stack       # Rebuild complete stack

Windows:

.\quickstart.ps1 -Rebuild                   # Rebuild backend only
.\quickstart.ps1 -Rebuild -FullStack          # Rebuild complete stack

Detailed Usage

Development Workflow

1. Start backend services:

   ./quickstart.sh
   

2. Start frontend in development mode:

   ./dev-start.sh
   

   Or manually:

   cd frontend
   npm install
   npm run start
   

3. Make changes to your code - Frontend will auto-reload

4. When backend code changes:

   ./quickstart.sh --rebuild
   

Production Testing

1. Build and run complete stack:

   ./quickstart.sh --full-stack
   

2. Test at http://localhost:80

3. When code changes:

   ./quickstart.sh --rebuild --full-stack
   

Command Reference

quickstart.sh / quickstart.ps1

Option	Description
(none)	Start backend services only (default)
--full-stack	Start complete stack including frontend
--rebuild	Force rebuild of containers
--help	Show help message

dev-start.sh / dev-start.ps1

Starts backend services + frontend development server with hot reload.

Stopping Services

Backend only:

docker-compose down

Complete stack:

docker-compose -f docker-compose.production.yml down

Logs

Backend services:

docker-compose logs -f

Complete stack:

docker-compose -f docker-compose.production.yml logs -f

Specific service:

docker-compose logs -f api
docker-compose logs -f postgres
docker-compose logs -f minio

Environment Variables

Copy .env.example to .env and modify as needed:

cp .env.example .env

The quickstart scripts will automatically create this file if it doesn't exist.

Troubleshooting

Container Issues

• Force rebuild: Use --rebuild flag
• Clean everything: docker-compose down --volumes --rmi all
• Check Docker: Ensure Docker Desktop is running

Frontend Issues

• Dependencies: Run npm install in frontend/ directory
• Port conflicts: Check if port 4200 is available
• Node version: Ensure Node.js 18+ is installed

Backend Issues

• API not responding: Wait longer for services to start (can take 30+ seconds)
• Database issues: Check docker-compose logs postgres
• Storage issues: Check docker-compose logs minio

Development vs Production

Feature	Development	Production
Frontend	Hot reload dev server	Built Angular app
Port	4200	80
Build time	Fast startup	Slower (builds Angular)
Use case	Development, testing	Demo, staging

Choose the mode that best fits your workflow!