Quickstart

Prerequisites

Before you begin, ensure you have the following installed on your system:

Java 21

Latest LTS version of Java. Download from Oracle or use SDKMAN

PostgreSQL

Version 12 or higher. Download from postgresql.org

Maven

Included with the project via Maven Wrapper (mvnw)

Git

For cloning the repository

The project includes Maven Wrapper (mvnw), so you don’t need to install Maven separately. The wrapper script will download the correct Maven version automatically.

Step 1: Clone the Repository

Start by cloning the Daily Tracker API repository:

git clone [email protected]:LorenzoPasquali/dailytracker-service.git
cd dailytracker-service

Step 2: Set Up PostgreSQL Database

Create a new PostgreSQL database for Daily Tracker:

PostgreSQL

CREATE DATABASE daily_tracker;

If you’re using a different database name, make sure to update the DATABASE_URL environment variable accordingly in the next step.

The application uses Flyway for database migrations, which will automatically create all necessary tables when the application starts.

Step 3: Configure Environment Variables

Daily Tracker API requires several environment variables. Create them in your shell or use a .env file:

Required Variables

.env

# Database connection (PostgreSQL)
DATABASE_URL="postgresql://username:password@localhost:5432/daily_tracker?schema=public"

# JWT secret key (minimum 32 characters)
JWT_SECRET="your_secure_jwt_secret_key_at_least_32_characters_long"

# Frontend URL for CORS and OAuth redirects
FRONTEND_URL="http://localhost:5173"

# Google OAuth2 credentials (optional, for social login)
GOOGLE_CLIENT_ID="your_google_client_id"
GOOGLE_CLIENT_SECRET="your_google_client_secret"

# AES encryption secret for sensitive data
AES_SECRET="your_aes_encryption_secret_key_32_chars"

Optional Variables

Optional

# Server port (default: 3000)
PORT=3000

Security Best Practice: Never commit your .env file or secrets to version control. The .gitignore file already excludes common secret files.

Environment Variable Details

Variable	Description	Required	Default
`DATABASE_URL`	PostgreSQL connection string. Supports both Prisma format and standard JDBC URLs	Yes	-
`JWT_SECRET`	Secret key for signing JWT tokens. Must be at least 32 characters	Yes	-
`FRONTEND_URL`	URL of your frontend application for CORS and OAuth redirects	Yes	`http://localhost:5173`
`GOOGLE_CLIENT_ID`	Google OAuth2 Client ID from Google Cloud Console	No*	-
`GOOGLE_CLIENT_SECRET`	Google OAuth2 Client Secret from Google Cloud Console	No*	-
`AES_SECRET`	AES encryption key for storing sensitive API keys (32 characters)	Yes	-
`PORT`	Port number for the API server	No	`3000`

*Google OAuth credentials are only required if you want to enable Google social login. The API will work without them using email/password authentication.

Step 4: Generate JWT Secret

You need a strong, random secret key for JWT tokens. Generate one using:

openssl rand -base64 48

Copy the output and use it as your JWT_SECRET environment variable.

Step 5: Set Up Google OAuth2 (Optional)

If you want to enable Google login, follow these steps:

Create Google Cloud Project

Go to Google Cloud Console and create a new project or select an existing one.

Enable Google+ API

In the API Library, search for “Google+ API” and enable it for your project.

Create OAuth2 Credentials

Navigate to Credentials → Create Credentials → OAuth 2.0 Client ID

Application type: Web application
Authorized redirect URIs: http://localhost:3000/auth/google/callback

Copy Credentials

Copy the Client ID and Client Secret to your environment variables.

For production deployments, add your production domain to the authorized redirect URIs (e.g., https://yourdomain.com/auth/google/callback).

Step 6: Run the Application

Now you’re ready to start the API server. Use the Maven wrapper to run the application:

export DATABASE_URL="postgresql://username:password@localhost:5432/daily_tracker"
export JWT_SECRET="your_generated_secret_key_here"
export FRONTEND_URL="http://localhost:5173"
export AES_SECRET="your_aes_secret_key_32_characters"

./mvnw spring-boot:run

The application will:

Download dependencies (first run only)
Run Flyway migrations to set up the database schema
Start the Spring Boot application
Listen on port 3000 (or your configured PORT)

The first run may take a few minutes as Maven downloads all dependencies. Subsequent runs will be much faster.

You should see output similar to:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::               (v3.5.11)

INFO: Started DailytrackerServiceApplication in 3.456 seconds

Step 7: Verify Installation

Check that the API is running by calling the health check endpoint:

cURL

curl http://localhost:3000/healthz

You should receive:

OK

Step 8: Make Your First API Request

Now let’s register a user and make an authenticated request.

Register a New User

cURL

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123",
    "language": "en-US"
  }'

Response:

{
  "message": "Usuário criado com sucesso!",
  "userId": 1
}

cURL

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "550e8400-e29b-41d4-a716-446655440000",
  "type": "Bearer"
}

Save the token value - you’ll need it for authenticated requests. The token is valid for 24 hours by default.

Get User Profile (Authenticated)

Use the token from the login response to make an authenticated request:

cURL

curl http://localhost:3000/api/user/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Replace YOUR_TOKEN_HERE with the actual token from the login response. Response:

{
  "id": 1,
  "email": "[email protected]",
  "language": "en-US"
}

Create Your First Task

cURL

curl -X POST http://localhost:3000/api/tasks \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My first task",
    "description": "Getting started with Daily Tracker API",
    "completed": false
  }'

Response:

{
  "id": 1,
  "title": "My first task",
  "description": "Getting started with Daily Tracker API",
  "completed": false,
  "createdAt": "2026-03-09T23:15:00Z",
  "updatedAt": "2026-03-09T23:15:00Z",
  "order": 0,
  "userId": 1
}

What’s Next?

Congratulations! You now have Daily Tracker API running locally. Here’s what to explore next:

Authentication Guide

Deep dive into JWT authentication, token refresh, and OAuth2 flows

API Reference

Explore all available endpoints with detailed schemas and examples

Environment Variables

Complete guide to all configuration options

Deployment Guide

Learn how to deploy to production environments

Troubleshooting

Database Connection Errors

If you see errors about database connections:

Verify PostgreSQL is running: pg_isready
Check your DATABASE_URL format and credentials
Ensure the database exists: psql -l
Check PostgreSQL logs for connection issues

JWT Secret Too Short

If you see “JWT secret must be at least 32 characters”:

Generate a new secret using the commands in Step 4
Ensure your JWT_SECRET environment variable is set correctly

Port Already in Use

If port 3000 is already in use:

Set a different port: export PORT=8080
Or stop the process using port 3000

Maven Dependencies Not Downloading

If Maven can’t download dependencies:

Check your internet connection
Try clearing Maven cache: rm -rf ~/.m2/repository
Run with verbose output: ./mvnw spring-boot:run -X

If you encounter issues not covered here, check the GitHub Issues page or create a new issue with details about your problem.

Get Started

Guides

Prerequisites

Java 21

PostgreSQL

Maven

Git

Step 1: Clone the Repository

Step 2: Set Up PostgreSQL Database

Step 3: Configure Environment Variables

Required Variables

Optional Variables

Environment Variable Details

Step 4: Generate JWT Secret

Step 5: Set Up Google OAuth2 (Optional)

Step 6: Run the Application

Step 7: Verify Installation

Step 8: Make Your First API Request

Register a New User

Get User Profile (Authenticated)

Create Your First Task

What’s Next?

Authentication Guide

API Reference

Environment Variables

Deployment Guide

Troubleshooting

Database Connection Errors

JWT Secret Too Short

Port Already in Use

Maven Dependencies Not Downloading

Build docs developers (and LLMs) love

Get Started

Guides

​Prerequisites

Java 21

PostgreSQL

Maven

Git

​Step 1: Clone the Repository

​Step 2: Set Up PostgreSQL Database

​Step 3: Configure Environment Variables

​Required Variables

​Optional Variables

​Environment Variable Details

​Step 4: Generate JWT Secret

​Step 5: Set Up Google OAuth2 (Optional)

​Step 6: Run the Application

​Step 7: Verify Installation

​Step 8: Make Your First API Request

​Register a New User

​Login to Get JWT Token

​Get User Profile (Authenticated)

​Create Your First Task

​What’s Next?

Authentication Guide

API Reference

Environment Variables

Deployment Guide

​Troubleshooting

​Database Connection Errors

​JWT Secret Too Short

​Port Already in Use

​Maven Dependencies Not Downloading

Build docs developers (and LLMs) love

Prerequisites

Step 1: Clone the Repository

Step 2: Set Up PostgreSQL Database

Step 3: Configure Environment Variables

Required Variables

Optional Variables

Environment Variable Details

Step 4: Generate JWT Secret

Step 5: Set Up Google OAuth2 (Optional)

Step 6: Run the Application

Step 7: Verify Installation

Step 8: Make Your First API Request

Register a New User

Login to Get JWT Token

Get User Profile (Authenticated)

Create Your First Task

What’s Next?

Troubleshooting

Database Connection Errors

JWT Secret Too Short

Port Already in Use

Maven Dependencies Not Downloading