xpeditis2.0/INSTALLATION-STEPS.md

# 📦 Installation Steps - Xpeditis

Complete step-by-step installation guide for the Xpeditis platform.

---

## Current Status

✅ **Sprint 0 Complete** - All infrastructure files created
⏳ **Dependencies** - Need to be installed
⏳ **Services** - Need to be started

---

## Installation Instructions

### Step 1: Install Dependencies

The project uses npm workspaces. Run this command from the root directory:

```bash
npm install
```

**What this does**:
- Installs root dependencies (prettier, typescript)
- Installs backend dependencies (~50 packages including NestJS, TypeORM, Redis, etc.)
- Installs frontend dependencies (~30 packages including Next.js, React, Tailwind, etc.)
- Links workspace packages

**Expected Output**:
- This will take 2-3 minutes
- You may see deprecation warnings (these are normal)
- On Windows, you might see `EISDIR` symlink warnings (these can be ignored - dependencies are still installed)

**Verification**:
```bash
# Check that node_modules exists
ls node_modules

# Check backend dependencies
ls apps/backend/node_modules

# Check frontend dependencies
ls apps/frontend/node_modules
```

---

### Step 2: Start Docker Infrastructure

Start PostgreSQL and Redis:

```bash
docker-compose up -d
```

**What this does**:
- Pulls PostgreSQL 15 Alpine image (if not cached)
- Pulls Redis 7 Alpine image (if not cached)
- Starts PostgreSQL on port 5432
- Starts Redis on port 6379
- Runs database initialization script
- Creates persistent volumes

**Verification**:
```bash
# Check containers are running
docker-compose ps

# Expected output:
# NAME                    STATUS        PORTS
# xpeditis-postgres       Up (healthy)  0.0.0.0:5432->5432/tcp
# xpeditis-redis          Up (healthy)  0.0.0.0:6379->6379/tcp

# Check logs
docker-compose logs

# Test PostgreSQL connection
docker-compose exec postgres psql -U xpeditis -d xpeditis_dev -c "SELECT version();"

# Test Redis connection
docker-compose exec redis redis-cli -a xpeditis_redis_password ping
# Should return: PONG
```

---

### Step 3: Setup Environment Variables

#### Backend

```bash
cp apps/backend/.env.example apps/backend/.env
```

**Default values work for local development!** You can start immediately.

**Optional customization** (edit `apps/backend/.env`):
```env
# These work out of the box:
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=xpeditis
DATABASE_PASSWORD=xpeditis_dev_password
DATABASE_NAME=xpeditis_dev

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=xpeditis_redis_password

JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

# Add these later when you have credentials:
# MAERSK_API_KEY=your-key
# GOOGLE_CLIENT_ID=your-client-id
# etc.
```

#### Frontend

```bash
cp apps/frontend/.env.example apps/frontend/.env
```

**Default values**:
```env
NEXT_PUBLIC_API_URL=http://localhost:4000
NEXT_PUBLIC_API_PREFIX=api/v1
```

---

### Step 4: Start Backend Development Server

```bash
# Option 1: From root
npm run backend:dev

# Option 2: From backend directory
cd apps/backend
npm run dev
```

**What happens**:
- NestJS compiles TypeScript
- Connects to PostgreSQL
- Connects to Redis
- Starts server on port 4000
- Watches for file changes (hot reload)

**Expected output**:
```
[Nest] 12345  - 10/07/2025, 3:00:00 PM     LOG [NestFactory] Starting Nest application...
[Nest] 12345  - 10/07/2025, 3:00:00 PM     LOG [InstanceLoader] ConfigModule dependencies initialized
[Nest] 12345  - 10/07/2025, 3:00:00 PM     LOG [InstanceLoader] TypeOrmModule dependencies initialized
...

    ╔═══════════════════════════════════════╗
    ║                                       ║
    ║   🚢 Xpeditis API Server Running     ║
    ║                                       ║
    ║   API: http://localhost:4000/api/v1  ║
    ║   Docs: http://localhost:4000/api/docs  ║
    ║                                       ║
    ╚═══════════════════════════════════════╝
```

**Verification**:
```bash
# Test health endpoint
curl http://localhost:4000/api/v1/health

# Or open in browser:
# http://localhost:4000/api/v1/health

# Open Swagger docs:
# http://localhost:4000/api/docs
```

---

### Step 5: Start Frontend Development Server

In a **new terminal**:

```bash
# Option 1: From root
npm run frontend:dev

# Option 2: From frontend directory
cd apps/frontend
npm run dev
```

**What happens**:
- Next.js compiles TypeScript
- Starts dev server on port 3000
- Watches for file changes (hot reload)
- Enables Fast Refresh

**Expected output**:
```
  ▲ Next.js 14.0.4
  - Local:        http://localhost:3000
  - Network:      http://192.168.1.x:3000

 ✓ Ready in 2.3s
```

**Verification**:
```bash
# Open in browser:
# http://localhost:3000

# You should see the Xpeditis homepage
```

---

## ✅ Installation Complete!

You should now have:

| Service | URL | Status |
|---------|-----|--------|
| **Frontend** | http://localhost:3000 | ✅ Running |
| **Backend API** | http://localhost:4000/api/v1 | ✅ Running |
| **API Docs** | http://localhost:4000/api/docs | ✅ Running |
| **PostgreSQL** | localhost:5432 | ✅ Running |
| **Redis** | localhost:6379 | ✅ Running |

---

## Troubleshooting

### Issue: npm install fails

**Solution**:
```bash
# Clear npm cache
npm cache clean --force

# Delete node_modules
rm -rf node_modules apps/*/node_modules packages/*/node_modules

# Retry
npm install
```

### Issue: Docker containers won't start

**Solution**:
```bash
# Check Docker is running
docker --version

# Check if ports are in use
# Windows:
netstat -ano | findstr :5432
netstat -ano | findstr :6379

# Mac/Linux:
lsof -i :5432
lsof -i :6379

# Stop any conflicting services
# Then retry:
docker-compose up -d
```

### Issue: Backend won't connect to database

**Solution**:
```bash
# Check PostgreSQL is running
docker-compose ps

# Check PostgreSQL logs
docker-compose logs postgres

# Verify connection manually
docker-compose exec postgres psql -U xpeditis -d xpeditis_dev

# If that works, check your .env file:
# DATABASE_HOST=localhost (not 127.0.0.1)
# DATABASE_PORT=5432
# DATABASE_USER=xpeditis
# DATABASE_PASSWORD=xpeditis_dev_password
# DATABASE_NAME=xpeditis_dev
```

### Issue: Port 4000 or 3000 already in use

**Solution**:
```bash
# Find what's using the port
# Windows:
netstat -ano | findstr :4000

# Mac/Linux:
lsof -i :4000

# Kill the process or change the port in:
# Backend: apps/backend/.env (PORT=4000)
# Frontend: package.json dev script or use -p flag
```

### Issue: Module not found errors

**Solution**:
```bash
# Backend
cd apps/backend
npm install

# Frontend
cd apps/frontend
npm install

# If still failing, check tsconfig.json paths are correct
```

---

## Common Development Tasks

### View Logs

```bash
# Backend logs (already in terminal)

# Docker logs
docker-compose logs -f

# PostgreSQL logs only
docker-compose logs -f postgres

# Redis logs only
docker-compose logs -f redis
```

### Database Operations

```bash
# Connect to PostgreSQL
docker-compose exec postgres psql -U xpeditis -d xpeditis_dev

# List tables
\dt

# Describe a table
\d table_name

# Run migrations (when created)
cd apps/backend
npm run migration:run
```

### Redis Operations

```bash
# Connect to Redis
docker-compose exec redis redis-cli -a xpeditis_redis_password

# List all keys
KEYS *

# Get a value
GET key_name

# Flush all data
FLUSHALL
```

### Run Tests

```bash
# Backend unit tests
cd apps/backend
npm test

# Backend tests with coverage
npm run test:cov

# Backend E2E tests
npm run test:e2e

# Frontend tests
cd apps/frontend
npm test

# All tests
npm run test:all
```

### Code Quality

```bash
# Format code
npm run format

# Check formatting
npm run format:check

# Lint backend
npm run backend:lint

# Lint frontend
npm run frontend:lint
```

---

## Next Steps

Now that everything is installed and running:

1. **📚 Read the docs**:
   - [QUICK-START.md](QUICK-START.md) - Quick reference
   - [README.md](README.md) - Full documentation
   - [CLAUDE.md](CLAUDE.md) - Architecture guidelines

2. **🛠️ Start developing**:
   - Check [TODO.md](TODO.md) for the roadmap
   - Review [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) for what's done
   - Begin Phase 1: Domain entities and ports

3. **🧪 Write tests**:
   - Domain layer tests (90%+ coverage target)
   - Integration tests for repositories
   - E2E tests for API endpoints

4. **🚀 Deploy** (when ready):
   - Review production checklist in SPRINT-0-FINAL.md
   - Update environment variables
   - Setup CI/CD pipelines

---

## Success Checklist

Before moving to Phase 1, verify:

- [ ] `npm install` completed successfully
- [ ] Docker containers running (postgres + redis)
- [ ] Backend starts without errors
- [ ] Frontend starts without errors
- [ ] Health endpoint returns 200 OK
- [ ] Swagger docs accessible
- [ ] Frontend homepage loads
- [ ] Tests pass (`npm test`)
- [ ] No TypeScript errors
- [ ] Hot reload works (edit a file, see changes)

---

**You're ready to build! 🎉**

For questions, check the documentation or open an issue on GitHub.

---

*Xpeditis - Maritime Freight Booking Platform*