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:

export COMPOSE_BAKE=true

Or add it to your .env file:

COMPOSE_BAKE=true

🚀 Quick Start

1. Setup Environment

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

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

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

./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:

# 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

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

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

# 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! 🚀