kidsai/DOCKER_MIGRATION.md

# KidsAI Explorer - Docker Migration Guide 🚀

## Migration to Next.js 15 + TypeScript + Tailwind CSS + Docker

This project has been successfully migrated from a vanilla Express.js application to a modern Next.js 15 setup with full Docker containerization.

## 🚀 Key Features

- **Next.js 15** with App Router
- **TypeScript** for type safety
- **Tailwind CSS** for modern styling
- **Docker & Docker Compose v2** for containerization
- **Docker Bake** support for improved build performance
- **Multi-stage builds** for optimized production images
- **Bilingual support** (English/German)
- **OpenAI API integration** for AI functionality

## 🏗️ Docker Bake Support

This project now supports **Docker Bake** for better build performance. To enable it:

```bash
export COMPOSE_BAKE=true
```

Or add it to your `.env` file:
```env
COMPOSE_BAKE=true
```

## 🚀 Quick Start

### 1. Setup Environment

```bash
# Copy environment template
cp .env.example .env

# Edit .env file and add your API keys
nano .env
```

### 2. Run with Docker (Recommended)

Using the convenient script:
```bash
# Make script executable (first time only)
chmod +x docker-dev.sh

# Start development environment
./docker-dev.sh dev

# Or start production environment
./docker-dev.sh prod
```

Manual Docker commands:
```bash
# Development
docker-compose up --build

# Production
docker-compose --profile production up --build app-prod
```

### 3. Available Commands

The `docker-dev.sh` script provides convenient commands:

```bash
./docker-dev.sh dev         # Start development environment
./docker-dev.sh prod        # Start production environment
./docker-dev.sh build       # Build all images using Docker Bake
./docker-dev.sh build-dev   # Build development image
./docker-dev.sh build-prod  # Build production image
./docker-dev.sh stop        # Stop all services
./docker-dev.sh clean       # Clean up containers and images
./docker-dev.sh logs        # Show application logs
./docker-dev.sh shell       # Open shell in running container
./docker-dev.sh help        # Show help
```

## 🏗️ Docker Architecture

### Multi-stage Dockerfile

The Dockerfile uses multi-stage builds for optimal performance:

- **base**: Common Node.js Alpine base
- **deps**: Production dependencies only
- **development**: Development environment with hot reload
- **builder**: Build stage for production
- **production**: Optimized production image

### Docker Bake Configuration

The `docker-bake.hcl` file defines build targets:

- **default**: Standard build
- **development**: Development build
- **production**: Production build with optimizations

### Services

- **app**: Development service (port 4000)
- **app-prod**: Production service (port 4001) 
- **database**: Optional PostgreSQL (for future Prisma integration)

## 🌐 Application Architecture

```
src/
├── app/                 # Next.js App Router
│   ├── layout.tsx      # Root layout
│   ├── page.tsx        # Home page
│   ├── globals.css     # Global styles
│   └── api/            # API routes
│       └── chat/       # AI chat endpoint
├── components/         # React components
│   ├── Header.tsx
│   ├── QuestionInput.tsx
│   ├── ThinkingSection.tsx
│   └── ...
├── lib/               # Utilities and configurations
│   ├── translations.ts # I18n translations
│   └── ai-service.ts  # AI service integration
└── types/             # TypeScript type definitions
    └── index.ts
```

## 🔧 Environment Variables

Required environment variables:

```env
# Docker Bake Support
COMPOSE_BAKE=true

# AI Service
OPENAI_API_KEY=your_openai_api_key_here
HUGGING_FACE_TOKEN=your_hugging_face_token_here

# Application
NODE_ENV=development
PORT=3000
```

## 🚀 Performance Optimizations

### Docker Bake Benefits

1. **Parallel builds**: Multiple targets built simultaneously
2. **Better caching**: Improved layer caching across builds
3. **Multi-platform**: Easy cross-platform builds
4. **Build context optimization**: Smarter file copying

### Next.js Optimizations

1. **App Router**: Modern routing with React Server Components
2. **TypeScript**: Compile-time error checking
3. **Tailwind CSS**: Utility-first CSS with tree-shaking
4. **Image optimization**: Built-in Next.js image optimization

## 🔄 Migration Summary

### What Changed

- ✅ **Express.js** → **Next.js 15 App Router**
- ✅ **Vanilla JS** → **TypeScript**
- ✅ **Custom CSS** → **Tailwind CSS**
- ✅ **Local server** → **Docker containerization**
- ✅ **Simple build** → **Multi-stage Docker builds**
- ✅ **Manual deployment** → **Docker Compose orchestration**

### What Stayed the Same

- ✅ **Bilingual support** (English/German)
- ✅ **Educational AI guidance**
- ✅ **Kid-friendly interface**
- ✅ **OpenAI integration**
- ✅ **Core functionality**

## 🐛 Troubleshooting

### Common Issues

1. **Port conflicts**: Make sure ports 3000/3001 are available
2. **Docker not running**: Ensure Docker daemon is started
3. **Environment variables**: Check `.env` file is properly configured
4. **Build failures**: Try `./docker-dev.sh clean` then rebuild

### Debug Commands

```bash
# Check container logs
docker-compose logs app

# Shell into container
docker-compose exec app sh

# Check environment variables
docker-compose exec app env

# Rebuild from scratch
docker-compose down --rmi all
docker-compose up --build
```

## 📚 Development

### Local Development (without Docker)

If you prefer local development:

```bash
# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

# Start production server
npm start
```

### Adding Features

1. **New components**: Add to `src/components/`
2. **New pages**: Add to `src/app/`
3. **API routes**: Add to `src/app/api/`
4. **Styling**: Use Tailwind CSS classes
5. **Types**: Add to `src/types/`

## 🎯 Next Steps

### Optional Enhancements

1. **Prisma Database**: Uncomment database service in `docker-compose.yml`
2. **Redis Caching**: Add Redis service for session management
3. **Nginx Proxy**: Add reverse proxy for production
4. **CI/CD Pipeline**: GitHub Actions with Docker Bake
5. **Monitoring**: Add health checks and logging

### Prisma Setup (Optional)

```bash
# Install Prisma
npm install prisma @prisma/client

# Initialize Prisma
npx prisma init

# Generate client
npx prisma generate

# Run migrations
npx prisma migrate dev
```

## 🏆 Success!

Your KidsAI Explorer is now running in a modern, containerized environment with:

- ⚡ **Fast builds** with Docker Bake
- 🔧 **Type safety** with TypeScript  
- 🎨 **Modern styling** with Tailwind CSS
- 🐳 **Containerized** deployment
- 🌍 **Production ready** setup

Access your application at:
- **Development**: http://localhost:4000
- **Production**: http://localhost:4001

Happy coding! 🚀