React (Next.js) + Spring Boot + Docker + Postgres + Nginx Boilerplate

A tested working boilerplate template for modern full-stack web applications with React frontend, Java Spring Boot backend, Docker containerization, and Nginx reverse proxy for singular frontend + backend port/domain access.

🔗 Original Repository: https://github.com/iairu/react-springboot-docker-boilerplate

📌 Service Versions

🚀 What's Included

This boilerplate provides a foundation with:

📋 Prerequisites

🛠 Quick Start

1. Clone the Repository

git clone https://github.com/iairu/react-springboot-docker-boilerplate.git
cd react-springboot-docker-boilerplate

2. Launch with Docker

# Start all services
docker compose up

# Or rebuild and start (useful after code changes)
docker compose build --no-cache
docker compose up

3. Access Your Application

🏗 Project Structure

├── frontend-react/          # React/Next.js frontend application
├── backend-java-springboot/  # Spring Boot backend application  
├── nginx-reverse-proxy/      # Nginx configuration for reverse proxy
├── .github/workflows/        # GitHub Actions CI/CD pipeline
├── docker-compose.yml        # Multi-container orchestration
├── .env.local.example       # Environment variables template
└── README.md                # This file

🔧 Development Workflow

Local Development

Quick Restart

Often used after minor config changes, inconsistencies, or computer reboot:

# Turn off
docker compose down

# Stop and remove all remaining Docker containers and networks (adjust prefix if needed)
docker stop $(docker ps -a -q -f name=react-springboot-) ; docker rm -f $(docker ps -a -q -f name=react-springboot-) ; docker network rm $(docker network ls -q -f name=react-springboot_)

# Turn on again
docker compose up -d

One-line restart command (recommended to add to .bashrc as an alias):

docker compose down ; docker stop $(docker ps -a -q -f name=react-springboot-) ; docker rm -f $(docker ps -a -q -f name=react-springboot-) ; docker network rm $(docker network ls -q -f name=react-springboot_) ; docker compose up -d

Full Rebuild

Use after major changes (especially if package.json or pom.xml changed):

# Turn off
docker compose down

# Stop and remove all remaining Docker containers and networks
docker stop $(docker ps -a -q -f name=react-springboot-) ; docker rm -f $(docker ps -a -q -f name=react-springboot-) ; docker network rm $(docker network ls -q -f name=react-springboot_)

# Rebuild without cache (important!)
docker compose build --no-cache

# Turn on
docker compose up -d

One-line rebuild command (recommended to add to .bashrc as an alias):

docker compose down ; docker stop $(docker ps -a -q -f name=react-springboot-) ; docker rm -f $(docker ps -a -q -f name=react-springboot-) ; docker network rm $(docker network ls -q -f name=react-springboot_) ; docker compose build --no-cache ; docker compose up -d

Selective Service Rebuild

# Rebuild specific service
docker compose build --no-cache backend
docker compose build --no-cache frontend
docker compose build --no-cache nginx

# Restart only nginx after config changes
docker compose stop nginx && docker compose build nginx && docker compose up -d nginx

View Logs

# View all logs
docker compose logs -f

# View logs for specific service
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f postgres

# View logs for specific container by ID
docker logs <container_id>

Stop Services

# Stop all services (keeps containers)
docker compose stop

# Stop and remove all services
docker compose down

Nuclear Option - Complete Docker Reset

⚠️ WARNING: This will remove ALL containers and images on your machine, not just this project!

Consider backing up other containers first!

# Stop and remove all Docker containers, then remove all images
docker stop $(docker ps -a -q) ; docker rm -f $(docker ps -a -q) ; docker rmi $(docker images -q)

# Remove all volumes and networks
docker system prune -a --volumes --force

# Start fresh
docker compose up -d

Debugging Commands

# List all containers (running and stopped)
docker container ls -a

# Get bash shell in a container
docker exec -it <container-name> /bin/bash

# If bash is not available, try sh
docker exec -it <container-name> /bin/sh

# Inspect container details
docker inspect <container-name>

# Check Docker disk usage
docker system df

Making Changes

  1. Frontend changes: Edit files in frontend-react/
  2. Backend changes: Edit files in backend-java-springboot/
  3. Nginx config: Edit nginx-reverse-proxy/nginx.conf
  4. Rebuild affected containers and restart

🚀 Deployment

GitHub Pages (Automatic)

The repository includes GitHub Actions that automatically:

  1. Builds the application on push to main
  2. Generates static files using Docker
  3. Deploys to GitHub Pages

Manual Deployment

# Production build
docker compose -f docker-compose.prod.yml up --build

# Or deploy to your preferred hosting service

🔌 API Integration

The frontend uses Axios to communicate with the Spring Boot backend:

// Example API call (already implemented)
import axios from 'axios';

const response = await axios.get('/api/hello.json');
console.log(response.data);

Backend provides REST endpoints:

// Example controller (already implemented)
@RestController
@RequestMapping("/api")
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello from Spring Boot!";
    }
    
    @GetMapping("/users")
    public List<User> getAllUsers() {
        return userRepository.findAll();
    }
}

🔧 Customization

Adding New API Endpoints

  1. Add controller methods in backend-java-springboot/src/main/java/
  2. Rebuild backend: docker compose build --no-cache backend
  3. Call from frontend using Axios

Adding Frontend Pages

  1. Add React components in frontend-react/src/
  2. Update routing as needed
  3. Rebuild frontend: docker compose build --no-cache frontend

Environment Configuration

Environment variables are optional but available for customization:

  1. Copy the example file:

    cp .env.local.example .env.local

  2. Edit your settings in .env.local:

    # .env.local
REACT_APP_API_URL=http://localhost/api
SPRING_PROFILES_ACTIVE=development

  3. Enable in Docker by uncommenting the env_file and environment lines in docker-compose.yml

The boilerplate works perfectly without any environment configuration!

📦 Technology Stack

🗄️ Database Features

Available API Endpoints

🐛 Troubleshooting

Common Issues

Port conflicts:

# Check what's using port 80
sudo lsof -i :80
# Kill conflicting processes or change ports in docker-compose.yml

Container build fails:

# Clean Docker cache
docker system prune -a
# Rebuild from scratch
docker compose build --no-cache --pull

Database connection issues:

# Check PostgreSQL logs
docker compose logs postgres
# Check backend connection logs
docker compose logs backend
# Verify database health
curl http://localhost/api/health

API calls fail:

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Make your changes
  4. Test with docker compose up
  5. Submit a pull request

📄 License

This project is licensed under the MIT License

Happy coding! 🚀 If you find this boilerplate helpful, please give it a star ⭐