Spring Boot + Next.js Full-Stack Template

Team Members

• Claire
• Jenny
• Julia
• Laurie

A modern full-stack web application template featuring Spring Boot backend and Next.js frontend with Docker-based development environment.

Zero-install development setup - Get started instantly with Docker containers for all services and dependencies. No need to install Java, Gradle, or databases locally.

Table of Contents

• Features
• Prerequisites
• Initial Setup
• Quick Start
• Development Commands
• Project Structure
• API Integration
• Development Notes
• CI/CD Pipeline
• Deployment
• Troubleshooting

Features

• Full-Stack Integration - Spring Boot 3.5.6 backend with Next.js 15.5.4 frontend
• Containerized Development - Backend runs in Docker, frontend runs locally for optimal development experience
• Instant Setup - No local Java/Gradle installation required for backend
• Live Reload - Automatic code changes with Spring Boot DevTools and Next.js hot reload
• Complete Stack - PostgreSQL database, Redis cache, and Mailpit email testing
• API Integration - Seamless communication between frontend and backend with CORS configuration
• Type Safety - TypeScript interfaces for API responses and centralized API client
• CI/CD Ready - GitHub Actions workflows for linting, building, and testing
• Simple Commands - Easy-to-use sail CLI for all development tasks

Prerequisites

• Docker Desktop (macOS/Windows) or Docker Engine (Linux)
• Node.js 22.20.0 (see .nvmrc file for exact version)
• Terminal access for running commands
• (Windows users) Git Bash or WSL recommended for best experience

Note: No Java or Gradle installation needed - backend runs in Docker containers.

🏫 School Network Users - Important Note

If you're on a school network with security restrictions, you may need to:

• Use a specific NVM mirror for Node.js installation
• Temporarily disable SSL verification for npm installs

See the Initial Setup section for detailed instructions.

Initial Setup

1. Install Required Software

Docker Desktop

• Download from: https://www.docker.com/products/docker-desktop/
• Install and start Docker Desktop (takes a moment to boot)

Visual Studio Code

• Download from: https://code.visualstudio.com/download
• Install and verify it works

Git

• Windows users: Download from https://gitforwindows.org/ (includes Git Bash)

• Mac users: Install Xcode Command Line Tools: xcode-select --install

  🍎 Mac Users - Xcode Command Line Tools

  If you don't have Git installed on Mac, run this command in Terminal:

  xcode-select --install

  This will install Git and other essential development tools. You may be prompted to install additional software - click "Install" when prompted.

2. Clone the Repository

1. Open the repository: https://github.com/HolyNamesAcademy/Projects-II-25-26/
2. Click the green "Code" button and copy the repository URL
3. Open VSCode and click "Clone Repository"
4. Paste the repository URL and clone
5. Open the project in VSCode

3. Fix Line Endings (Windows Users Only)

🪟 Windows Users - Line Endings Fix

To ensure all files use Linux (LF) line endings (required for Docker and shell scripts), run this command in Git Bash:

find . -type f -not -path '*/\.git/*' -exec dos2unix {} +; git checkout .

This converts Windows (CRLF) line endings to Unix (LF) format, which is required for proper Docker container execution.

4. Install Node Version Manager (NVM)

Install NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Configure NVM:

• Windows (Git Bash): nano ~/.bash_profile
• Mac: nano ~/.zshrc

Add this content:

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Save with: Ctrl+X, then Y, then Enter

Open a new terminal (Git Bash on Windows)

5. Install Node.js

🏫 School Network (with security restrictions)

NVM_NODEJS_ORG_MIRROR=http://nodejs.org/dist nvm install

🏠 Home Network

nvm install

6. Install Project Dependencies

🏫 School Network (with security restrictions)

cd frontend
# Disable SSL verification temporarily for school network
npm config set strict-ssl false
npm install
# Re-enable SSL verification for security
npm config set strict-ssl true

🏠 Home Network

cd frontend
npm install

7. Verify Your Setup

After completing all setup steps, verify everything is working:

# Check if Docker is running
docker --version

# Check if Node.js is installed
node --version  # Should show v22.20.0

# Check if Git is working
git --version

# Test the sail script
./sail --version

If any of these commands fail, go back to the relevant setup step above.

Quick Start

First time? Make sure you've completed the Initial Setup steps above.

1. Start the development environment:

   ./sail up

2. Run the backend:

   ./sail backend

3. Run the frontend (in a new terminal):

   ./sail frontend

4. Verify everything is working:

   • Open http://localhost:3000 - you should see the frontend
   • Open http://localhost:8080/api/health - you should see {"status":"UP"}

🌐 Development URLs

Service	URL	Description
Frontend	http://localhost:3000	Main application interface
Backend API	http://localhost:8080/api	REST API endpoints
Mailpit UI	http://localhost:8025	Email testing interface (SMTP: 1025)
PostgreSQL	localhost:5432	Database (user: app, pass: app, db: app)
Redis	localhost:6379	Cache and session storage

Development Commands

Full-Stack Development

./sail up        Start dev environment (services only)
./sail down      Stop everything
./sail restart   Restart all containers

Backend Commands

./sail run       Run the backend (hot reload via devtools)
./sail backend   Run the backend (alias for run)
./sail debug     Run the backend with debug port 5005 enabled
./sail test      Run backend tests in the container
./sail clean     Clean build artifacts in the container
./sail backend:lint Run backend checkstyle and SpotBugs linting

Frontend Commands

./sail frontend       Run the frontend dev server
./sail frontend:dev   Run the frontend dev server (alias)
./sail frontend:build Build the frontend for production
./sail frontend:start Start the frontend production server
./sail frontend:lint  Run frontend linting

Docker Commands

./sail build     Rebuild the app image
./sail sh        Shell into the app container (bash)
./sail logs      Tail all container logs
./sail ps        Show container status
./sail status    Check Docker daemon and container status
./sail psql      Open psql in the Postgres container
./sail redis-cli Open redis-cli in the Redis container

🚀 Common Workflows

Daily Development

# Start your day
./sail up              # Start all services
./sail backend         # Run backend (Terminal 1)
./sail frontend        # Run frontend (Terminal 2)

Making Changes

# Backend changes - automatic restart via DevTools
# Frontend changes - automatic hot reload

# Test your changes
./sail test            # Run backend tests
./sail frontend:lint   # Check frontend code quality

Debugging Issues

./sail ps              # Check what's running
./sail logs            # View all logs
./sail status          # Check Docker status

Stopping Everything

./sail down            # Stop all containers

Project Structure

├── backend/                    # Spring Boot backend
│   ├── src/main/java/         # Java source code
│   │   └── com/hna/webserver/
│   │       ├── config/        # CORS configuration
│   │       └── controller/    # REST controllers
│   ├── src/main/resources/    # Application configuration
│   │   ├── application.properties
│   │   └── application-dev.yml # Docker dev profile
│   ├── build.gradle           # Gradle build configuration
│   └── config/checkstyle/     # Code quality configuration
├── frontend/                  # Next.js frontend
│   ├── src/app/              # App router pages
│   │   └── page.tsx          # Home page
│   ├── src/lib/              # API utilities
│   │   └── api.ts            # Centralized API client
│   ├── package.json          # Frontend dependencies
│   ├── next.config.ts        # Next.js configuration
│   └── tsconfig.json         # TypeScript configuration
├── .github/workflows/         # GitHub Actions CI/CD workflows
│   ├── ci.yml                # Main CI pipeline
│   ├── backend-*.yml         # Backend-specific workflows
│   └── frontend-*.yml        # Frontend-specific workflows
├── docker-compose.yml         # Docker services configuration
├── Dockerfile.dev             # App container image
├── .nvmrc                     # Node.js version specification
├── sail                       # Command helper script
└── README.md                  # This file

API Integration

Using the API

import { api } from '@/lib/api';

// Example usage
const data = await api.hello();

Development Notes

• Hot reload: Spring Boot DevTools for backend, Next.js hot reload for frontend
• CORS: Configured to allow frontend requests from localhost:3000
• API Proxying: Next.js automatically proxies /api/* to backend
• Type Safety: TypeScript interfaces for all API responses
• Profiles: Backend runs with SPRING_PROFILES_ACTIVE=dev in Docker
• Database: PostgreSQL configured for development
• Caching: Redis available for caching
• Email: Mailpit for email testing

Development Workflow

1. Start services: ./sail up (starts Docker containers)
2. Run backend: ./sail backend (in one terminal)
3. Run frontend: ./sail frontend (in another terminal)
4. Make changes: Edit code in your IDE
5. See changes: Frontend updates automatically, backend restarts automatically
6. Test API: Use curl http://localhost:8080/api/health or test endpoints directly

CI/CD Pipeline

The .github/workflows/ folder contains GitHub Actions workflows that automatically run on every push and pull request, handling linting, building, and testing for both frontend and backend.

Deployment

This template is ready for deployment to any cloud provider that supports Spring Boot and Next.js applications. Update the environment variables in your deployment platform to point to your production services.

Troubleshooting

Common Issues

🌐 CORS Errors

• Ensure backend is running on port 8080
• Check CORS configuration in backend/src/main/java/com/hna/webserver/config/CorsConfig.java
• Verify frontend is running on localhost:3000

🔌 API Connection Failed

• Verify backend is running: ./sail ps
• Check backend logs: ./sail logs
• Ensure services are up: ./sail up

⚛️ Frontend Not Loading

• Ensure Node.js version matches .nvmrc (22.20.0)
• Install dependencies: cd frontend && npm install
• Check if port 3000 is available

🗄️ Database Connection Issues

• Ensure PostgreSQL is running: ./sail ps
• Check database logs: ./sail logs db
• Verify connection settings in application-dev.yml

🐳 Docker Issues

• Check Docker daemon is running: ./sail status
• Restart Docker Desktop if needed
• Clean up containers: ./sail down && docker system prune
• Rebuild containers: ./sail build

🔌 Port Conflicts

• Ensure ports 3000, 8080, 5432, 6379, and 8025 are available
• Check what's using a port: lsof -i :PORT_NUMBER (macOS/Linux)
• Kill process using port: kill -9 PID (replace PID with actual process ID)

🪟 Windows Terminal Issues

• Always use Git Bash instead of PowerShell for running ./sail commands
• In VSCode, click the arrow next to the + button in terminal and select "Git Bash"
• If commands don't work, ensure you're in the project root directory

Debug Commands

# Check service status
./sail ps

# View all logs
./sail logs

# Check Docker status
./sail status

# Shell into backend container
./sail sh

# Test API endpoints directly
curl http://localhost:8080/api/health

Getting Help

If you're still having issues:

1. Check the logs: ./sail logs - look for error messages
2. Restart everything: ./sail restart
3. Verify your setup: Make sure you completed all Initial Setup steps
4. Check your environment: Ensure Docker is running and ports are available
5. Ask for help: Contact your instructor or team members

Quick Health Check

Run this command to verify everything is working:

# Check all services
./sail ps

# Test API connectivity
curl http://localhost:8080/api/health

# Check frontend
open http://localhost:3000