Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ccasro/hub/llms.txt

Use this file to discover all available pages before exploring further.

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=admin@yourdomain.com
MAIL_USERNAME=your_smtp_username
MAIL_PASSWORD=your_smtp_password
APP_MAIL_FROM=noreply@padelhub.com
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