Installation

Complete installation guide for Hub platform

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:

Backend

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)

The easiest way to get started is using Docker Compose.

Prerequisites

1. Install Docker

   Install Docker Desktop or Docker Engine:

   macOS

   # 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
   
2. Clone the Repository

   git clone <repository-url>
   cd hub
   
3. 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=[e-mail]
   
   # Application Configuration
   APP_ADMIN_EMAIL=[e-mail]
   APP_FRONTEND_URL=http://localhost:3000
   

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

4. 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
5. 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

1. Navigate to Frontend

   cd frontend/sports-hub-frontend
   
2. 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

3. 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
4. Start Development Server

   npm run dev
   

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

Local Development

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

Backend Setup

1. Install Java 21

   macOS

   # Using Homebrew
   brew install openjdk@21
   
   # Add to PATH
   echo 'export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   
2. Start PostgreSQL

   Start PostgreSQL with PostGIS using Docker:

   docker compose up -d postgres
   

   Or install PostgreSQL 16 locally with the PostGIS extension.

3. 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=[e-mail]
   export APP_MAIL_FROM=[e-mail]
   export APP_FRONTEND_URL=http://localhost:3000
   
4. 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)

Production

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

1. 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=[e-mail]
   
   # Application
   APP_ADMIN_EMAIL=[e-mail]
   APP_FRONTEND_URL=https://yourdomain.com
   
   # Disable Swagger in production
   SWAGGER_ENABLED=false
   
2. 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
   
3. 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;
       }
   }
   
4. 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
   
5. 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:

1. Create Auth0 Application

   1. Go to Auth0 Dashboard
   2. Navigate to Applications > Applications
   3. Click Create Application
   4. Choose Regular Web Application
   5. Name it “Hub Platform”
2. 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.

3. Create Auth0 API

   1. Navigate to Applications > APIs
   2. Click Create API
   3. Set:
      • Name: Hub API
      • Identifier: https://api.yourdomain.com (this is your AUTH0_AUDIENCE)
      • Signing Algorithm: RS256
   4. Enable RBAC and Add Permissions in the Access Token
4. 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
5. 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:

1. Check Backend Health

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

   Expected response:

   {"status":"UP"}
   
2. Access API Documentation

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

3. 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).

4. 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