Quickstart

Get Hub up and running in under 10 minutes

Get your Hub platform running locally in under 10 minutes. This guide will take you from cloning the repository to accessing the application.

Prerequisites

Before you begin, ensure you have the following installed:

• Docker (version 20.10 or higher) and Docker Compose (v2.0+)
• Git for cloning the repository
• Node.js 18+ and npm for the frontend
• Java 21 for local backend development (optional)
• Auth0 account for authentication setup

If you’re just getting started, Docker and Docker Compose are all you need to run the full stack.

Quick Start

1. Clone the Repository

   Clone the Hub repository to your local machine:

   git clone <repository-url>
   cd hub
   
2. Configure Environment Variables

   Create a .env file in the root directory with the required environment variables:

   .env

   # Database Configuration
   POSTGRES_DB=hub
   POSTGRES_USER=hub_user
   POSTGRES_PASSWORD=your_secure_password
   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 (Image Storage)
   CLOUDINARY_CLOUD_NAME=your_cloud_name
   CLOUDINARY_API_KEY=your_api_key
   CLOUDINARY_API_SECRET=your_api_secret
   
   # Application Configuration
   APP_ADMIN_EMAIL=[e-mail]
   APP_MAIL_FROM=[e-mail]
   
   # Email Configuration (Brevo)
   MAIL_USERNAME=[e-mail]
   MAIL_PASSWORD=your_password
   

   Never commit your .env file to version control. Keep your credentials secure.

3. Configure Auth0

   Set up your Auth0 application:

   1. Create a new Auth0 application (Regular Web Application)
   2. Configure the following settings:
      • Allowed Callback URLs: http://localhost:3000/api/auth/callback
      • Allowed Logout URLs: http://localhost:3000
      • Allowed Web Origins: http://localhost:3000
   3. Create an API in Auth0 with the identifier matching your AUTH0_AUDIENCE
   4. Update your .env file with the Auth0 credentials
4. Start the Backend Services

   Use Docker Compose to start the PostgreSQL database and backend:

   docker compose up -d
   

   This will start:

   • PostgreSQL with PostGIS extension on port 5432
   • Spring Boot backend on port 8080
   • pgAdmin on port 5050 (optional database management)

   Verify the services are running:

   docker compose ps
   

   You should see all services in a “running” state.

5. Set Up Frontend Environment

   Navigate to the frontend directory and create a .env.local file:

   cd frontend/sports-hub-frontend
   

   Create .env.local with the following variables:

   .env.local

   # Auth0 Frontend Configuration
   AUTH0_SECRET=use_a_long_random_string_here
   AUTH0_BASE_URL=http://localhost:3000
   AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
   AUTH0_CLIENT_ID=your_client_id
   AUTH0_CLIENT_SECRET=your_client_secret
   AUTH0_AUDIENCE=https://api.yourdomain.com
   AUTH0_DOMAIN=your-tenant.auth0.com
   
   # API Configuration
   NEXT_PUBLIC_API_URL=http://localhost:8080
   

   Generate a secure random string for AUTH0_SECRET using: openssl rand -hex 32

6. Install Frontend Dependencies

   Install the required npm packages:

   npm install
   
7. Start the Frontend

   Run the Next.js development server:

   npm run dev
   

   The frontend will start on http://localhost:3000

8. Access the Application

   Open your browser and navigate to:

   http://localhost:3000
   

   You should see the Hub login page. Click the login button to authenticate with Auth0.

Verify Your Setup

Backend API

Check the backend health endpoint:

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

API Documentation

Access Swagger UI at:

http://localhost:8080/swagger-ui.html

Database Admin

Access pgAdmin at:

http://localhost:5050

Login: [e-mail] / admin

Frontend

Access the application at:

http://localhost:3000

Common Issues

Database connection failed

Make sure PostgreSQL is running and the credentials in your .env file match:

docker compose logs postgres

Check that the database is healthy:

docker compose ps postgres

Backend fails to start

Check the backend logs for errors:

docker compose logs backend

Common issues:

• Auth0 configuration is invalid
• Database connection failed
• Missing environment variables

Auth0 authentication fails

Verify that:

• Your Auth0 callback URLs are configured correctly
• The AUTH0_SECRET is set in .env.local
• The AUTH0_AUDIENCE matches between backend and frontend
• Your Auth0 application type is “Regular Web Application”

Frontend can't connect to backend

Ensure that:

• The backend is running on http://localhost:8080
• NEXT_PUBLIC_API_URL in .env.local is set to http://localhost:8080
• CORS is properly configured in the backend

Useful Commands

Quick reference for common development tasks:

# View all logs
docker compose logs -f

# View backend logs only
docker compose logs -f backend

# Restart all services
docker compose restart

# Stop all services
docker compose down

# Stop and remove volumes (reset database)
docker compose down -v

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

Next Steps

Installation Guide

Learn about detailed installation options and local development setup

API Reference

Explore the available API endpoints and authentication

Architecture

Understand the platform architecture and technology stack

Development Guide

Learn about the development workflow and best practices