Switch to angular

2025-10-14 23:32:38 -05:00
parent 1ce27976a9
commit 82e8cea256
72 changed files with 20815 additions and 991 deletions
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -0,0 +1,195 @@
+# 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:**
+```bash
+./quickstart.sh                # Backend services only
+./dev-start.sh                 # Backend + Frontend dev server
+```
+
+**Windows:**
+```powershell
+.\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:**
+```bash
+./quickstart.sh --full-stack
+```
+
+**Windows:**
+```cmd
+.\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:**
+```bash
+./quickstart.sh --rebuild                    # Rebuild backend only
+./quickstart.sh --rebuild --full-stack       # Rebuild complete stack
+```
+
+**Windows:**
+```cmd
+.\quickstart.ps1 -Rebuild                   # Rebuild backend only
+.\quickstart.ps1 -Rebuild -FullStack          # Rebuild complete stack
+```
+
+## Detailed Usage
+
+### Development Workflow
+
+1. **Start backend services:**
+   ```bash
+   ./quickstart.sh
+   ```
+
+2. **Start frontend in development mode:**
+   ```bash
+   ./dev-start.sh
+   ```
+   Or manually:
+   ```bash
+   cd frontend
+   npm install
+   npm run start
+   ```
+
+3. **Make changes to your code** - Frontend will auto-reload
+
+4. **When backend code changes:**
+   ```bash
+   ./quickstart.sh --rebuild
+   ```
+
+### Production Testing
+
+1. **Build and run complete stack:**
+   ```bash
+   ./quickstart.sh --full-stack
+   ```
+
+2. **Test at http://localhost:80**
+
+3. **When code changes:**
+   ```bash
+   ./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:**
+```bash
+docker-compose down
+```
+
+**Complete stack:**
+```bash
+docker-compose -f docker-compose.production.yml down
+```
+
+## Logs
+
+**Backend services:**
+```bash
+docker-compose logs -f
+```
+
+**Complete stack:**
+```bash
+docker-compose -f docker-compose.production.yml logs -f
+```
+
+**Specific service:**
+```bash
+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:
+
+```bash
+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!