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:

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:

# 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:

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:

# 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

cp apps/backend/.env.example apps/backend/.env

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

Optional customization (edit apps/backend/.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

cp apps/frontend/.env.example apps/frontend/.env

Default values:

NEXT_PUBLIC_API_URL=http://localhost:4000
NEXT_PUBLIC_API_PREFIX=api/v1

---

Step 4: Start Backend Development Server

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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

# 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

# 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

# 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 reference
   • README.md - Full documentation
   • CLAUDE.md - Architecture guidelines

2. 🛠️ Start developing:

   • Check TODO.md for the roadmap
   • Review 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