Complete Docker migration with Next.js 15 and cleaned design
- Migrated from Express.js to Next.js 15 with TypeScript - Added Docker Compose v2 with multi-stage builds - Implemented Docker Bake support for improved builds - Created professional component structure with Tailwind CSS - Added enhanced visual design with glass morphism effects - Improved responsive layout and better UX flow - Updated all dependencies and configurations - Added proper TypeScript types and modern practices - Created development scripts for easy container management - Cleaned up excessive animations for better user experience
This commit is contained in:
mindesbunister
277
DOCKER_MIGRATION.md
Normal file
277
DOCKER_MIGRATION.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 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! 🚀
|
||||
Reference in New Issue
Block a user