Skip to main content
This guide will walk you through setting up the Macondo Link Manager development environment on your local machine.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 20 or higher (specified in engines)
  • Docker and Docker Compose
  • Git for version control
  • npm package manager
The project requires Node.js version 20 or higher. Check your version with node --version.

​
Architecture Overview

Macondo Link Manager is organized as a monorepo containing:
  • /api - Backend (Fastify + Prisma + PostgreSQL)
  • /web - Frontend (Next.js 14 with App Router)

​
Quick Start with Docker

The easiest way to get started is using Docker Compose, which sets up both the database and API automatically.
1
Clone the repository
2
git clone <repository-url>
cd macondo-link-manager
3
Configure environment variables
4
Copy the example environment file and configure it:
5
cp .env.example .env
6
Edit .env with your configuration:
7
# Postgres
POSTGRES_DB=macondo_links
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password
DATABASE_URL=postgresql://postgres:your_secure_password@postgres:5432/macondo_links

# API Base URL
BASE_URL=http://localhost:3333

# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# JWT Secret
JWT_SECRET=generate_a_random_string_here

# Frontend URL
FRONTEND_URL=http://localhost:3000

# Environment
NODE_ENV=development
NODE_VERSION=20
PORT=3333
8
Never commit the .env file to version control. Always use .env.example as a template.
9
Start the services
10
Build and start all services with Docker Compose:
11
docker-compose up --build
12
This will:
13
  • Start PostgreSQL on port 5432
  • Start the API on port 3333
  • Expose Prisma Studio on port 5555
  • Run database migrations automatically
  • Generate Prisma Client
    • 14
    Verify the setup
    15
    Check that the API is running:
    16
    curl http://localhost:3333/health
    17
    Expected response:
    18
    {
  "status": "ok",
  "dbConnection": "healthy"
}

    ​
    Manual Setup (Without Docker)

    If you prefer to run services individually:
    1
    Install PostgreSQL
    2
    Install PostgreSQL 15 locally and create a database:
    3
    psql -U postgres
CREATE DATABASE macondo_links;
    4
    Configure environment variables
    5
    Update your .env file with the local database connection:
    6
    DATABASE_URL=postgresql://postgres:password@localhost:5432/macondo_links
    7
    Install backend dependencies
    8
    cd api
npm install
    9
    Generate Prisma Client
    10
    npm run prisma:generate
    11
    Run database migrations
    12
    npx prisma migrate dev
    13
    Start the API server
    14
    npm run dev
    15
    The API will start on http://localhost:3333.
    16
    Install frontend dependencies
    17
    In a new terminal:
    18
    cd web
npm install
    19
    Start the frontend server
    20
    npm run dev
    21
    The frontend will start on http://localhost:3000.

    ​
    Google OAuth Setup

    The application uses Google OAuth for authentication with corporate domain restriction.
    1
    Create Google Cloud Project
    2
  • Go to Google Cloud Console
  • Create a new project or select an existing one
  • Enable the Google+ API
    • 4
  • Navigate to APIs & Services → OAuth consent screen
  • Choose Internal (for corporate domain restriction)
  • Fill in application details
    • 5
    Create OAuth 2.0 Credentials
    6
  • Go to APIs & Services → Credentials
  • Click Create Credentials → OAuth 2.0 Client ID
  • Application type: Web application
  • Add authorized redirect URIs:
    • Development: http://localhost:3333/auth/google/callback
    • Production: https://li.mcd.ppg.br/auth/google/callback
    • 7
    Update environment variables
    8
    Add the credentials to your .env file:
    9
    GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here

    ​
    Database Management

    ​
    Prisma Studio

    Access the visual database browser: 
    cd api
npx prisma studio
    Prisma Studio will open at http://localhost:5555.

    ​
    Database Migrations

    Create a new migration after schema changes: 
    cd api
npx prisma migrate dev --name describe_your_changes

    ​
    Reset Database

    This will delete all data in your database. Only use in development.
    cd api
npx prisma migrate reset

    ​
    Environment Configuration

    ​
    Backend Environment Variables

    VariableDescriptionExample
    DATABASE_URLPostgreSQL connection stringpostgresql://user:pass@host:5432/db
    GOOGLE_CLIENT_IDGoogle OAuth Client IDFrom Google Cloud Console
    GOOGLE_CLIENT_SECRETGoogle OAuth SecretFrom Google Cloud Console
    JWT_SECRETSecret for JWT token signingRandom string (use password generator)
    BASE_URLAPI base URLhttp://localhost:3333
    FRONTEND_URLFrontend URL for CORShttp://localhost:3000
    NODE_ENVEnvironment modedevelopment or production
    PORTAPI server port3333

    ​
    Frontend Environment Variables

    The frontend uses Next.js and requires API configuration: Create web/.env.local: 
    NEXT_PUBLIC_API_URL=http://localhost:3333

    ​
    Troubleshooting

    Check that PostgreSQL is running and the DATABASE_URL is correct:
    # Test database connection
psql $DATABASE_URL

# If using Docker, check container status
docker ps

# View API logs
docker-compose logs api
    Common issues:
    • Database container not ready (wait 5-10 seconds)
    • Incorrect password or credentials
    • Port 5432 already in use
    Ensure the schema file is valid:
    cd api
npx prisma validate
npx prisma generate
    If using Docker, rebuild the container:
    docker-compose down
docker-compose up --build
    Verify:
    1. Redirect URI matches exactly in Google Cloud Console
    2. GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are correct
    3. FRONTEND_URL environment variable is set
    4. User email domain is authorized (for internal apps)
    Check if another service is using the port:
    # Check port 3333 (API)
lsof -i :3333

# Check port 3000 (Frontend)
lsof -i :3000

# Check port 5432 (PostgreSQL)
lsof -i :5432
    Kill the process or change the port in your configuration.
    The API uses MaxMind GeoLite2 for geolocation. If you see warnings:
    ⚠️  MAXMIND_LICENSE_KEY não definida. Pulando download.
    This is optional for development. To enable:
    1. Sign up at MaxMind
    2. Generate a license key
    3. Add to .env: MAXMIND_LICENSE_KEY=your_key
    4. Run: npm run geolite:download
    The app works without geolocation data (country/city will be null).

    ​
    Available Scripts

    ​
    Backend (api/)

    # Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Generate Prisma Client
npm run prisma:generate

# Download GeoLite2 databases
npm run geolite:download

    ​
    Frontend (web/)

    # Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run linter
npm run lint

    ​
    Next Steps

    Once your development environment is set up:

    ​
    Docker Compose Reference

    The docker-compose.yml configuration: 
    services:
  postgres:
    image: postgres:15-alpine
    container_name: macondo_links_db
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./pgdata:/var/lib/postgresql/data

  api:
    build:
      context: ./api
      dockerfile: Dockerfile.dev
    container_name: macondo_links_api
    ports:
      - "3333:3333"
      - "5555:5555"
    environment:
      DATABASE_URL: ${DATABASE_URL}
    depends_on:
      - postgres
    The API uses start.sh which:
    1. Installs dependencies
    2. Generates Prisma Client
    3. Waits for PostgreSQL to be ready
    4. Starts the development server with ts-node

    Build docs developers (and LLMs) love

    Get started for freeTalk to us