🐳 Docker Full-Stack Microservice Application

A modern, containerized full-stack application built with Docker, Node.js, Next.js, and MySQL. This project demonstrates best practices for building and deploying microservices using Docker containers.

📋 Table of Contents

• Features
• Tech Stack
• Project Structure
• Prerequisites
• Installation
• Usage
• API Endpoints
• Docker Configuration
• Environment Variables
• Development
• Production Deployment
• Troubleshooting
• Contributing
• License

✨ Features

• 🐳 Fully Dockerized - All services run in isolated containers
• 🔄 User Management - Complete CRUD operations for user data
• 🎨 Modern UI - Beautiful, responsive interface with Tailwind CSS
• 🔒 Secure - Non-root users, environment variables, and best practices
• 🚀 Auto-reconnect - Database connection with retry logic
• 📦 Microservices Architecture - Separate frontend, backend, and database services
• ⚡ Hot Reload - Development mode with instant updates

🛠️ Tech Stack

Frontend

• Next.js 15 - React framework with TypeScript
• Tailwind CSS - Utility-first CSS framework
• React Hooks - State management with useState and useEffect

Backend

• Node.js - JavaScript runtime
• Express.js - Web application framework
• MySQL2 - MySQL database driver
• CORS - Cross-Origin Resource Sharing support
• dotenv - Environment variable management

Database

• MySQL 8.0 - Relational database

DevOps

• Docker - Containerization platform
• Docker Compose - Multi-container orchestration

📁 Project Structure

fullstackapp/
├── backend/
│   ├── index.js              # Express server with API routes
│   ├── package.json          # Backend dependencies
│   ├── Dockerfile            # Backend container configuration
│   └── .dockerignore         # Files to exclude from Docker build
├── frontend/
│   ├── app/
│   │   ├── page.tsx          # Main UI component
│   │   ├── layout.tsx        # Root layout
│   │   └── globals.css       # Global styles
│   ├── package.json          # Frontend dependencies
│   ├── Dockerfile            # Frontend container configuration
│   ├── .dockerignore         # Files to exclude from Docker build
│   ├── next.config.ts        # Next.js configuration
│   └── tsconfig.json         # TypeScript configuration
├── docker-compose.yml        # Multi-container orchestration
└── README.md                 # Project documentation

📦 Prerequisites

Before running this application, make sure you have the following installed:

• Docker Desktop (version 20.10 or higher)
• Docker Compose (version 2.0 or higher)
• Git (for cloning the repository)

Check Installation

docker --version
docker-compose --version

🚀 Installation

1. Clone the repository

git clone https://github.com/codezelaca/microservise-docker-app.git
cd microservise-docker-app

2. Start the application

docker-compose up --build

This will:

• Pull the MySQL 8.0 image (first time only)
• Build the frontend and backend Docker images
• Start all three containers
• Set up the database with the users table

3. Access the application

• Frontend: http://localhost:3000
• Backend API: http://localhost:5000
• MySQL Database: localhost:3307

💻 Usage

Add a User

1. Navigate to http://localhost:3000
2. Fill in the "Name" and "Email" fields
3. Click "Add User"
4. The user will appear in the list below

Delete a User

1. Find the user in the list
2. Click the "Delete" button
3. The user will be removed from the database

🔌 API Endpoints

Health Check

GET /api/health

Returns the backend service status.

Get All Users

GET /api/users

Returns a list of all users.

Response:

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "created_at": "2026-03-01T12:00:00.000Z"
  }
]

Create User

POST /api/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

Response:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

Delete User

DELETE /api/users/:id

Response:

{
  "message": "User deleted"
}

🐳 Docker Configuration

Services

1. Database (MySQL)

• Image: mysql:8.0
• Port: 3307:3306
• Environment:
  • MYSQL_ROOT_PASSWORD=rootpassword
  • MYSQL_DATABASE=myapp
• Volume: Persistent data storage

2. Backend (Node.js)

• Build: ./backend
• Port: 5000:5000
• Dependencies: Waits for database to be healthy
• Features:
  • Database retry logic (10 attempts)
  • Automatic table creation
  • Non-root user for security

3. Frontend (Next.js)

• Build: ./frontend
• Port: 3000:3000
• Dependencies: Waits for backend to start
• Features:
  • Hot reload in development
  • Non-root user for security

Docker Best Practices Implemented

✅ Alpine Linux base images - Smaller image sizes ✅ Multi-stage optimization - Layer caching with package*.json ✅ npm ci - Faster, more reliable installations ✅ Cache cleaning - Reduced image sizes ✅ Non-root users - Enhanced security ✅ .dockerignore - Exclude unnecessary files ✅ Health checks - Ensure services are ready ✅ Dependency management - Proper service startup order

🌍 Environment Variables

Backend (.env)

DB_HOST=database
DB_USER=root
DB_PASSWORD=rootpassword
DB_NAME=myapp
PORT=5000

Frontend

NEXT_PUBLIC_API_URL=http://localhost:5000

🔧 Development

Start in Development Mode

docker-compose up

Rebuild After Changes

docker-compose up --build

Stop All Services

docker-compose down

View Logs

# All services
docker-compose logs

# Specific service
docker-compose logs backend
docker-compose logs frontend
docker-compose logs database

Access Container Shell

# Backend
docker exec -it fullstack_backend sh

# Frontend
docker exec -it fullstack_frontend sh

# Database
docker exec -it fullstack_mysql mysql -uroot -prootpassword myapp

Run Backend Locally (without Docker)

cd backend
npm install
# Make sure MySQL is running locally
node index.js

Run Frontend Locally (without Docker)

cd frontend
npm install
npm run dev

🚀 Production Deployment

For production, consider these modifications:

1. Use production builds

RUN npm run build
CMD ["npm", "start"]

2. Use secrets for passwords

secrets:
  db_password:
    external: true

3. Add nginx reverse proxy

4. Enable SSL/TLS certificates

5. Set up proper logging

6. Configure resource limits

🐛 Troubleshooting

Port Already in Use

Problem: Port 3306 already in use

Error: ports are not available: exposing port TCP 0.0.0.0:3306

Solution: The docker-compose.yml already uses port 3307 to avoid conflicts with local MySQL.

Permission Denied Error

Problem: Frontend can't create .next directory

Error: EACCES: permission denied, mkdir '/app/.next/dev'

Solution: Already fixed with chown -R nextjs:nodejs /app in Dockerfile.

Database Connection Failed

Problem: Backend cannot connect to database

Solution: Wait for the database to be healthy. The backend has retry logic (10 attempts with 5-second delays).

Cannot Fetch Users

Problem: Frontend shows "Failed to fetch"

Solution: Ensure backend is running and accessible at http://localhost:5000

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

codezelaca

• GitHub: @codezelaca
• Repository: microservise-docker-app

🙏 Acknowledgments

• Docker for containerization
• Next.js team for the amazing framework
• Express.js community
• MySQL for the reliable database

---

⭐ If you found this project helpful, please give it a star!

🐛 Found a bug? Open an issue