Skip to main content

​
Prerequisites

Before setting up the project, ensure you have the following installed:

Java 21

Required for backend development

Node.js 20+

Required for frontend development

Docker & Docker Compose

Required for running PostgreSQL and services

Maven

Java build tool (included via Maven Wrapper)

​
Initial Setup

1

Clone the repository

git clone <repository-url>
cd hub
2

Configure environment variables

Create a .env file in the project root with the following variables:
# Database
POSTGRES_DB=hub_db
POSTGRES_USER=hub_user
POSTGRES_PASSWORD=hub_password
DB_HOST=localhost
DB_PORT=5432

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

# Cloudinary (for image uploads)
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Email
APP_MAIL_FROM=[email protected]
BREVO_API_KEY=your-brevo-api-key

# Admin
APP_ADMIN_EMAIL=[email protected]

# Ports
BACKEND_PORT=8080
FRONTEND_PORT=3000
For local development, you can use dummy values for Auth0 and Cloudinary if you’re not testing those features.
3

Start infrastructure services

Use Docker Compose to start PostgreSQL and pgAdmin:
make up
This starts:
  • PostgreSQL (with PostGIS extension) on port 5432
  • pgAdmin on port 5050 (access at http://localhost:5050)
pgAdmin credentials: [email protected] / admin
4

Run the backend

The backend uses Spring Boot with Maven:
make backend-run
Or manually:
cd backend
./mvnw spring-boot:run
The API will be available at http://localhost:8080
5

Run the frontend

In a separate terminal, start the Next.js development server:
cd frontend/sports-hub-frontend
npm install
npm run dev
The frontend will be available at http://localhost:3000

​
Development Workflow

​
Backend Commands

The project includes a Makefile with helpful commands: 
make backend-run

​
Frontend Commands

npm run dev

​
Database Commands

make db-shell

​
API Documentation

Once the backend is running, you can access:
  • Swagger UI: http://localhost:8080/swagger-ui.html
  • OpenAPI Spec: http://localhost:8080/v3/api-docs

​
Code Quality

​
Backend

The project uses Spotless with Google Java Format for code formatting: 
# Apply formatting
make backend-format

# Check if formatting is needed
make backend-format-check
Always run make backend-format before committing to ensure consistent code style.

​
Frontend

The frontend uses ESLint for linting: 
npm run lint

​
Testing

​
Backend Tests

The backend uses JUnit 5 and Testcontainers for integration testing: 
make backend-test
Tests automatically spin up a PostgreSQL container for database testing.

​
Troubleshooting

​
Database Connection Issues

If the backend can’t connect to PostgreSQL:
  1. Ensure Docker containers are running: make ps
  2. Check database logs: make logs-db
  3. Verify environment variables in .env
  4. Try resetting the database: make db-reset && make up

​
Port Conflicts

If ports 5432, 8080, or 3000 are already in use:
  1. Stop conflicting services
  2. Or modify the port numbers in .env and docker-compose.yml

​
Maven Build Issues

If you encounter Maven build errors: 
make backend-clean
make backend-build

​
Next Steps

Architecture

Learn about the hexagonal architecture

Tech Stack

Explore the technologies used

Build docs developers (and LLMs) love

Get started for freeTalk to us