Skip to main content
The Hub platform uses Docker Compose to orchestrate multiple services for local development. This setup includes PostgreSQL with PostGIS, pgAdmin, and the Spring Boot backend.

​
Prerequisites

Ensure you have the following installed:
  • Docker Engine 20.10+
  • Docker Compose v2.0+
  • Make (optional, for using Makefile commands)

​
Architecture

The Docker Compose setup includes:
  • PostgreSQL with PostGIS: Main database with geographic data support
  • pgAdmin: Database administration interface
  • Backend: Spring Boot application (port 8080)
  • Frontend: Next.js application (commented out, runs separately)

​
Quick Start

1

Configure environment variables

Create a .env file in the project root with the required variables:
.env
# Database Configuration
POSTGRES_DB=hub
POSTGRES_USER=hubuser
POSTGRES_PASSWORD=your_secure_password
DB_HOST=postgres
DB_PORT=5432

# Backend Port
BACKEND_PORT=8080

# Auth0 Configuration
AUTH0_ISSUER=https://your-domain.auth0.com/
AUTH0_AUDIENCE=your-api-audience

# Cloudinary Configuration
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# Email Configuration
APP_ADMIN_EMAIL=[email protected]
MAIL_USERNAME=your_smtp_username
MAIL_PASSWORD=your_smtp_password
APP_MAIL_FROM=[email protected]
Never commit the .env file to version control. Keep your credentials secure.
2

Start all services

Use Docker Compose or Make to start the services:
docker compose up -d
The -d flag runs containers in detached mode (background).
3

Verify services are running

Check the status of all containers:
docker compose ps
All services should show a healthy status.
4

Access the services

Once running, access the services at:

​
Service Details

​
PostgreSQL Database

The database uses the official PostGIS image with geographic extensions: 
postgres:
  image: postgis/postgis:16-3.4
  ports:
    - "5432:5432"
Features:
  • PostgreSQL 16 with PostGIS 3.4
  • Health checks for dependency management
  • Persistent volume storage
  • Automatic restart unless stopped
The database includes a health check that ensures it’s ready before dependent services start.

​
Backend Service

The Spring Boot backend is built using a multi-stage Dockerfile: 
# Build stage
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn -q -DskipTests dependency:go-offline
COPY src ./src
RUN mvn -q -DskipTests package

# Run stage
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java","-jar","app.jar"]
Build optimizations:
  • Maven dependency caching for faster rebuilds
  • Multi-stage build reduces final image size
  • Only JRE in runtime image (smaller footprint)

​
pgAdmin

Web-based PostgreSQL administration tool:
Change the pgAdmin default password in production environments.

​
Common Commands

​
Using Make

The project includes a Makefile with convenient shortcuts: 
# Start all services
make up

# Stop all services
make down

# Restart all services
make restart

# View logs from all services
make logs

# View database logs only
make logs-db

# Open database shell
make db-shell

# Reset database (removes volumes)
make db-reset

​
Using Docker Compose

Direct Docker Compose commands: 
docker compose up -d

​
Development Workflow

​
Backend Development

For active backend development, you can run Spring Boot outside Docker:
1

Start database only

docker compose up -d postgres
2

Update DB_HOST in .env

DB_HOST=localhost
3

Run Spring Boot locally

make backend-run
Running the backend locally provides faster reload times during development.

​
Rebuilding After Changes

When you modify the backend code: 
# Rebuild and restart the backend container
docker compose up -d --build backend

​
Troubleshooting

​
Database Connection Issues

If the backend fails to connect to PostgreSQL:
  1. Check database health: 
    docker compose ps postgres
  2. View database logs: 
    make logs-db
  3. Verify environment variables are set correctly in .env

​
Port Conflicts

If ports are already in use:
  1. Check what’s using the port: 
    sudo lsof -i :8080
sudo lsof -i :5432
  2. Either stop the conflicting service or change the port in .env: 
    BACKEND_PORT=8081

​
Container Build Failures

If the backend container fails to build:
  1. Clean Maven cache: 
    make backend-clean
  2. Rebuild without cache: 
    docker compose build --no-cache backend

​
Database Reset

To completely reset the database:
This will delete all data. Use with caution.
make db-reset
make up

​
Volume Management

Persistent data is stored in Docker volumes:
  • postgres-data: Database files
  • pgadmin-data: pgAdmin configuration

​
Backup Database Volume

docker run --rm -v hub_postgres-data:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/postgres-backup.tar.gz /data

​
Restore Database Volume

docker run --rm -v hub_postgres-data:/data -v $(pwd):/backup \
  ubuntu tar xzf /backup/postgres-backup.tar.gz -C /

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us