Installation

This comprehensive guide covers all installation options for the Hub platform, from local development to production deployment.

System Requirements

Minimum Requirements

Development Environment

OS: Linux, macOS, or Windows (with WSL2)
RAM: 8GB minimum, 16GB recommended
Storage: 10GB free space
Docker: Version 20.10+
Docker Compose: v2.0+

Production Environment

RAM: 16GB minimum
CPU: 4 cores minimum
Storage: 50GB+ SSD recommended
OS: Ubuntu 22.04 LTS or similar
Network: Static IP recommended

Tech Stack Overview

Hub is built with modern technologies for scalability and performance:

Framework: Spring Boot 3.5.10
Language: Java 21
Build Tool: Maven 3.9
Database: PostgreSQL 16 with PostGIS 3.4
Authentication: OAuth2 + JWT (Auth0)
Image Storage: Cloudinary
Email Service: Brevo
API Documentation: SpringDoc OpenAPI 3

Installation Methods

Docker (Recommended)
Local Development
Production

The easiest way to get started is using Docker Compose.

Prerequisites

Install Docker

Install Docker Desktop or Docker Engine:

# Using Homebrew
brew install --cask docker

# Or download from Docker website
# https://www.docker.com/products/docker-desktop

Verify installation:

docker --version
docker compose version

Clone the Repository

git clone <repository-url>
cd hub

Configure Environment

Create a .env file in the project root:

.env

# Database Configuration
POSTGRES_DB=hub
POSTGRES_USER=hub_user
POSTGRES_PASSWORD=your_secure_password_here
DB_HOST=postgres
DB_PORT=5432

# Backend Configuration
BACKEND_PORT=8080

# Auth0 Configuration
AUTH0_ISSUER=https://your-tenant.auth0.com/
AUTH0_AUDIENCE=https://api.yourdomain.com

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

# Email Configuration
MAIL_USERNAME=your_brevo_email
MAIL_PASSWORD=your_brevo_smtp_key
APP_MAIL_FROM=[email protected]

# Application Configuration
APP_ADMIN_EMAIL=[email protected]
APP_FRONTEND_URL=http://localhost:3000

Replace all placeholder values with your actual configuration. Never commit .env files to version control.

Start Services

Launch all services with Docker Compose:

# Start in detached mode
docker compose up -d

# View logs
docker compose logs -f

# Check service status
docker compose ps

The following services will start:

PostgreSQL: localhost:5432
Spring Boot Backend: localhost:8080
pgAdmin: localhost:5050

Verify Database

Check that the database is ready and migrations have run:

# Access database shell
docker compose exec postgres psql -U hub_user -d hub

# In psql, list tables
\dt

# Check PostGIS extension
SELECT PostGIS_version();

# Exit psql
\q

You should see tables for venues, bookings, users, resources, payments, and match requests.

Configure Frontend

Navigate to Frontend

cd frontend/sports-hub-frontend

Create Environment File

Create .env.local:

.env.local

# Auth0 Configuration
AUTH0_SECRET=generate_32_byte_random_string
AUTH0_BASE_URL=http://localhost:3000
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
AUTH0_CLIENT_ID=your_auth0_client_id
AUTH0_CLIENT_SECRET=your_auth0_client_secret
AUTH0_AUDIENCE=https://api.yourdomain.com
AUTH0_DOMAIN=your-tenant.auth0.com

# Backend API
NEXT_PUBLIC_API_URL=http://localhost:8080

Generate AUTH0_SECRET: openssl rand -hex 32

Install Dependencies

npm install

This installs all required packages including:

Next.js 16 and React 19
Auth0 Next.js SDK
Radix UI components
Tailwind CSS
TypeScript

Start Development Server

npm run dev

The frontend will be available at http://localhost:3000

Run the backend and frontend locally without Docker (requires Java 21 and Node.js).

Backend Setup

Install Java 21

# Using Homebrew
brew install openjdk@21

# Add to PATH
echo 'export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Start PostgreSQL

Start PostgreSQL with PostGIS using Docker:

docker compose up -d postgres

Or install PostgreSQL 16 locally with the PostGIS extension.

Configure Backend Environment

Set environment variables in your shell or IDE:

export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=hub
export DB_USER=hub_user
export DB_PASSWORD=your_password
export AUTH0_ISSUER=https://your-tenant.auth0.com/
export AUTH0_AUDIENCE=https://api.yourdomain.com
export CLOUDINARY_CLOUD_NAME=your_cloud_name
export CLOUDINARY_API_KEY=your_api_key
export CLOUDINARY_API_SECRET=your_api_secret
export MAIL_USERNAME=your_email
export MAIL_PASSWORD=your_password
export APP_ADMIN_EMAIL=admin@yourdomain.com
export APP_MAIL_FROM=noreply@padelhub.com
export APP_FRONTEND_URL=http://localhost:3000

Run Backend

cd backend

# Run with Maven wrapper
./mvnw spring-boot:run

# Or build and run JAR
./mvnw clean package
java -jar target/backend-0.0.1-SNAPSHOT.jar

The backend will start on http://localhost:8080

Frontend Setup

Follow the same frontend steps as the Docker installation above.

Useful Make Commands

The project includes a Makefile for common tasks:

# View available commands
make help

# Backend commands
make backend-run          # Run Spring Boot
make backend-build        # Build JAR
make backend-test         # Run tests
make backend-format       # Format code
make backend-format-check # Check formatting

# Docker commands
make up                   # Start docker compose
make down                 # Stop docker compose
make logs                 # Follow all logs
make ps                   # Show container status

# Database commands
make db-shell             # Access PostgreSQL shell
make db-reset             # Reset database (removes volumes)

Deploy Hub to a production environment.

Prerequisites

Ubuntu 22.04 LTS server (or similar)
Docker and Docker Compose installed
Domain name configured
SSL/TLS certificates (Let’s Encrypt recommended)
Production database (managed PostgreSQL recommended)

Production Configuration

Prepare Environment

Create a production .env file with secure values:

.env

# Database (use managed PostgreSQL in production)
POSTGRES_DB=hub_production
POSTGRES_USER=hub_prod_user
POSTGRES_PASSWORD=strong_random_password_here
DB_HOST=your-postgres-host.provider.com
DB_PORT=5432

# Backend
BACKEND_PORT=8080

# Auth0
AUTH0_ISSUER=https://your-tenant.auth0.com/
AUTH0_AUDIENCE=https://api.yourdomain.com

# Cloudinary
CLOUDINARY_CLOUD_NAME=your_production_cloud
CLOUDINARY_API_KEY=your_production_key
CLOUDINARY_API_SECRET=your_production_secret

# Email
MAIL_USERNAME=your_production_email
MAIL_PASSWORD=your_production_smtp_key
APP_MAIL_FROM=[email protected]

# Application
APP_ADMIN_EMAIL=[email protected]
APP_FRONTEND_URL=https://yourdomain.com

# Disable Swagger in production
SWAGGER_ENABLED=false

Update docker-compose.yml

Modify for production use:

docker-compose.prod.yml

services:
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: hub-backend
    restart: always
    environment:
      DB_HOST: ${DB_HOST}
      DB_PORT: ${DB_PORT}
      DB_NAME: ${POSTGRES_DB}
      DB_USER: ${POSTGRES_USER}
      DB_PASSWORD: ${POSTGRES_PASSWORD}
      AUTH0_ISSUER: ${AUTH0_ISSUER}
      AUTH0_AUDIENCE: ${AUTH0_AUDIENCE}
      CLOUDINARY_CLOUD_NAME: ${CLOUDINARY_CLOUD_NAME}
      CLOUDINARY_API_KEY: ${CLOUDINARY_API_KEY}
      CLOUDINARY_API_SECRET: ${CLOUDINARY_API_SECRET}
      APP_ADMIN_EMAIL: ${APP_ADMIN_EMAIL}
      MAIL_USERNAME: ${MAIL_USERNAME}
      MAIL_PASSWORD: ${MAIL_PASSWORD}
      APP_MAIL_FROM: ${APP_MAIL_FROM}
      APP_FRONTEND_URL: ${APP_FRONTEND_URL}
      SWAGGER_ENABLED: ${SWAGGER_ENABLED}
      SPRING_PROFILES_ACTIVE: production
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Add nginx for reverse proxy
  nginx:
    image: nginx:alpine
    container_name: hub-nginx
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - backend

Configure Nginx

Create nginx.conf:

nginx.conf

upstream backend {
    server backend:8080;
}

server {
    listen 80;
    server_name api.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;

    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Deploy Frontend

Build and deploy the Next.js frontend:

cd frontend/sports-hub-frontend

# Set production environment variables
export AUTH0_SECRET=your_production_secret
export AUTH0_BASE_URL=https://yourdomain.com
export AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
export AUTH0_CLIENT_ID=your_production_client_id
export AUTH0_CLIENT_SECRET=your_production_client_secret
export AUTH0_AUDIENCE=https://api.yourdomain.com
export AUTH0_DOMAIN=your-tenant.auth0.com
export NEXT_PUBLIC_API_URL=https://api.yourdomain.com

# Build
npm run build

# Start in production mode
npm start

# Or deploy to Vercel/Netlify

Start Production Services

docker compose -f docker-compose.prod.yml up -d

Security Checklist:

Use strong, unique passwords
Enable SSL/TLS for all connections
Disable Swagger UI in production
Use managed database with backups
Configure firewall rules
Set up monitoring and logging
Regular security updates

Auth0 Configuration

Detailed Auth0 setup for authentication:

Create Auth0 Application

Go to Auth0 Dashboard
Navigate to Applications > Applications
Click Create Application
Choose Regular Web Application
Name it “Hub Platform”

Configure Application Settings

In your application settings:Application URIs:

Allowed Callback URLs:

http://localhost:3000/api/auth/callback,
https://yourdomain.com/api/auth/callback

Allowed Logout URLs:

http://localhost:3000,
https://yourdomain.com

Allowed Web Origins:

http://localhost:3000,
https://yourdomain.com

Save your settings.

Create Auth0 API

Navigate to Applications > APIs
Click Create API
Set:
- Name: Hub API
- Identifier: https://api.yourdomain.com (this is your AUTH0_AUDIENCE)
- Signing Algorithm: RS256
Enable RBAC and Add Permissions in the Access Token

Configure API Permissions

Add the following permissions (scopes):

read:venues - Read venue information
write:venues - Create and update venues
read:bookings - Read bookings
write:bookings - Create and manage bookings
read:profile - Read user profile
write:profile - Update user profile

Copy Credentials

From your Auth0 application, copy:

Domain (e.g., your-tenant.auth0.com)
Client ID
Client Secret

Use these in your .env and .env.local files.

Database Schema

The application uses Flyway migrations to manage the database schema. On startup, the following tables are created:

View Database Schema

Core Tables:

city - Spanish cities with geospatial data
users - User accounts and profiles
venue - Padel venues with location data
resource - Courts/resources at venues
booking - Court bookings
payment - Payment records
match_request - Match-making requests

PostGIS Extensions:

postgis - Spatial database extension
pgcrypto - Cryptographic functions
btree_gist - Generalized index support

The database includes pre-seeded data for major Spanish cities including Madrid, Barcelona, Valencia, Sevilla, and others.

Verification

After installation, verify everything is working:

Check Backend Health

curl http://localhost:8080/actuator/health

Expected response:

{"status":"UP"}

Access API Documentation

Open http://localhost:8080/swagger-ui.html in your browser to view the OpenAPI documentation.

Test Database Connection

docker compose exec postgres psql -U hub_user -d hub -c "SELECT COUNT(*) FROM city;"

Should return a count of cities (seeded data).

Verify Frontend

Open http://localhost:3000 and test:

Page loads successfully
Login button is visible
Auth0 login flow works

Troubleshooting

Port Already in Use

If you see “port already in use” errors:

# Check what's using the port
lsof -i :8080
lsof -i :3000
lsof -i :5432

# Kill the process or change ports in .env
BACKEND_PORT=8081

Database Migration Fails

If Flyway migrations fail:

# Check migration history
docker compose exec postgres psql -U hub_user -d hub -c "SELECT * FROM flyway_schema_history;"

# Reset database (CAUTION: deletes all data)
docker compose down -v
docker compose up -d

Auth0 JWT Validation Error

If you see JWT validation errors:

Verify AUTH0_ISSUER ends with a trailing slash
Ensure AUTH0_AUDIENCE matches between backend and frontend
Check that your Auth0 API is configured for RS256
Verify the token has not expired

Cloudinary Upload Fails

If image uploads fail:

Verify your Cloudinary credentials in .env
Check that your Cloudinary account is active
Ensure the cloud name, API key, and secret are correct
Test credentials at the Cloudinary Console

Frontend Build Errors

If Next.js build fails:

# Clear Next.js cache
rm -rf .next

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Rebuild
npm run build

Next Steps

Development Guide

Learn about the development workflow and coding standards

API Reference

Explore the REST API endpoints and authentication

Architecture

Understand the system architecture and design patterns

Configuration

Configure environment variables and integrations

Get Started

Core Features

User Guides

Configuration

Installation

System Requirements

Minimum Requirements

Development Environment

Production Environment

Tech Stack Overview

Installation Methods

Prerequisites

Configure Frontend

Backend Setup

Frontend Setup

Useful Make Commands

Prerequisites

Production Configuration

Auth0 Configuration

Database Schema

Verification

Troubleshooting

Next Steps

Development Guide

API Reference

Architecture

Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Configuration

​System Requirements

​Minimum Requirements

Development Environment

Production Environment

​Tech Stack Overview

​Installation Methods

​Prerequisites

​Configure Frontend

​Backend Setup

​Frontend Setup

​Useful Make Commands

​Prerequisites

​Production Configuration

​Auth0 Configuration

​Database Schema

​Verification

​Troubleshooting

​Next Steps

Development Guide

API Reference

Architecture

Configuration

Build docs developers (and LLMs) love

System Requirements

Minimum Requirements

Tech Stack Overview

Installation Methods

Prerequisites

Configure Frontend

Backend Setup

Frontend Setup

Useful Make Commands

Prerequisites

Production Configuration

Auth0 Configuration

Database Schema

Verification

Troubleshooting

Next Steps