Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
Docker Desktop includes Docker Compose, so you don’t need to install it separately if you’re using Docker Desktop.

​
Setup steps

1

Clone the repository

Clone the library management system repository to your local machine:
git clone https://github.com/yigit-7/library-management-system.git
cd library-management-system
The repository is organized as a monorepo:
  • apps/spring-boot-app - Backend application
  • apps/nextjs-app - Frontend application
  • compose.yaml - Docker Compose configuration for all services
2

Configure environment variables

Create a .env file in the root directory by copying the example file:
cp .env.example .env
Open the .env file and configure the following variables:
# PostgreSQL Credentials
POSTGRES_USER=library_admin
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=library_db

# Backend Configuration
BACKEND_PORT=8080
Choose a strong password for POSTGRES_PASSWORD in production environments. Avoid using simple passwords like “password” or “123456”.
3

Start the services

Launch all services using Docker Compose:
docker-compose -f compose.yaml up --build
This command will:
  • Build Docker images for the frontend and backend
  • Start PostgreSQL database (port 5432)
  • Start Redis cache (internal)
  • Start Spring Boot backend (port 8080)
  • Start Next.js frontend (port 3000)
The first run will take several minutes as Docker builds the images and downloads dependencies. Subsequent starts will be much faster.
The services will start in the following order:
  1. PostgreSQL database
  2. Redis cache
  3. Spring Boot backend (waits for database and cache health checks)
  4. Next.js frontend (waits for backend health check)
4

Verify the installation

Once all containers are running, you can access:

Frontend

http://localhost:3000The Next.js application with the user interface

Backend API

http://localhost:8080The Spring Boot REST API

API documentation

http://localhost:8080/swagger-ui.htmlInteractive API documentation powered by SpringDoc

Health check

http://localhost:8080/actuator/healthBackend health status
You can verify all containers are running:
docker-compose ps
You should see all four services (database, cache, backend, frontend) with status “Up” and “healthy”.

​
Docker Compose architecture

The compose.yaml file defines the complete application stack:
compose.yaml
services:
  database:
    image: postgres:15-alpine
    container_name: library-db
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  cache:
    image: redis:7-alpine
    container_name: library-cache

  backend:
    build: ./apps/spring-boot-app
    container_name: library-backend
    ports:
      - "${BACKEND_PORT:-8080}:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://database:5432/${POSTGRES_DB}
      SPRING_DATASOURCE_USERNAME: ${POSTGRES_USER}
      SPRING_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD}
      SPRING_DATA_REDIS_HOST: cache
      SPRING_DATA_REDIS_PORT: 6379
    depends_on:
      database:
        condition: service_healthy
      cache:
        condition: service_healthy

  frontend:
    build: ./apps/nextjs-app
    container_name: library-frontend
    ports:
      - "3000:3000"
    environment:
      API_INTERNAL_URL: http://backend:8080
      NEXT_PUBLIC_API_URL: http://localhost:8080
    depends_on:
      backend:
        condition: service_healthy

volumes:
  postgres_data:
The configuration uses health checks to ensure services start in the correct order. The frontend won’t start until the backend is healthy, and the backend won’t start until the database and cache are ready.

​
Managing the application

​
Stop the services

To stop all running services: 
docker-compose down
This stops and removes the containers but preserves the database volume.

​
Stop and remove data

To stop services and remove all data (including the database): 
docker-compose down -v
The -v flag deletes the PostgreSQL data volume. You’ll lose all data in the database.

​
View logs

To view logs from all services: 
docker-compose logs -f
To view logs from a specific service: 
docker-compose logs -f backend
docker-compose logs -f frontend

​
Restart a service

To restart a specific service: 
docker-compose restart backend

​
Development workflow

For local development without Docker, you can run services individually:

​
Start infrastructure only

Start just the database and cache: 
docker-compose -f compose.infra.yaml up
This is useful when you want to run the backend and frontend directly on your machine for faster development iterations.

​
Backend development

With infrastructure running, start the Spring Boot backend: 
cd apps/spring-boot-app
./mvnw spring-boot:run
The backend requires Java 21 installed locally.

​
Frontend development

Start the Next.js frontend: 
cd apps/nextjs-app
npm install
npm run dev
The frontend requires Node.js 20 or higher.

​
Troubleshooting

If you see an error about ports being in use (3000, 5432, or 8080), you can either:
  • Stop the service using that port
  • Change the port in the .env file (for backend) or compose.yaml (for frontend/database)
Check what’s using a port:
# On Linux/Mac
lsof -i :8080

# On Windows
netstat -ano | findstr :8080
If the backend can’t connect to the database:
  1. Ensure the database container is healthy: docker-compose ps
  2. Verify environment variables in .env match the database configuration
  3. Check database logs: docker-compose logs database
If Docker build fails:
  1. Ensure you have enough disk space
  2. Try cleaning Docker cache: docker system prune -a
  3. Pull the latest base images: docker-compose pull
  4. Rebuild without cache: docker-compose build --no-cache
If the frontend shows connection errors:
  1. Verify the backend is running: curl http://localhost:8080/actuator/health
  2. Check that NEXT_PUBLIC_API_URL in the frontend environment is set to http://localhost:8080
  3. Ensure there are no CORS issues in the browser console

​
Next steps

Authentication

Learn how to authenticate users with JWT tokens

Book management

Explore book CRUD operations and management features

API reference

Browse the complete API documentation

Environment configuration

Configure the system for production deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us