Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:
  • Node.js version 18 or higher
  • Docker and Docker Compose
  • Git for cloning the repository
  • A Google Cloud account for OAuth configuration

​
Installation

1

Clone the repository

Clone the Macondo Link Manager monorepo to your local machine:
git clone <repository-url>
cd macondo-link-manager
2

Configure environment variables

Create a .env file in the root directory by copying the example file:
cp .env.example .env
Update the .env file with your configuration:
# Postgres Configuration
POSTGRES_DB=macondo_links
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password
DATABASE_URL=postgresql://postgres:your_secure_password@localhost:5432/macondo_links

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

# Google OAuth Credentials
# Get these from Google Cloud Console
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# JWT Secret
# Generate a random string for signing tokens
JWT_SECRET=your_random_jwt_secret

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

# Environment
NODE_ENV=development
NODE_VERSION=20
PORT=3333
Make sure to replace placeholder values with actual credentials. For Google OAuth, create a project in Google Cloud Console and configure OAuth 2.0 credentials.
3

Set up Google OAuth

To enable authentication, configure Google OAuth:
  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Navigate to APIs & Services → Credentials
  4. Create OAuth 2.0 Client ID credentials
  5. Add authorized redirect URIs:
    • http://localhost:3333/auth/google/callback (development)
  6. Copy the Client ID and Client Secret to your .env file
In production, the system restricts authentication to your corporate domain. Configure this in your API settings.
4

Start the database

Launch PostgreSQL using Docker Compose:
docker-compose up -d postgres
Verify the database is running:
docker ps
You should see the macondo_links_db container running on port 5432.
5

Set up the database schema

Navigate to the API directory and run Prisma migrations:
cd api

npm install
npm run prisma:generate
npx prisma migrate dev
This will:
  • Install backend dependencies
  • Generate the Prisma Client
  • Apply all database migrations
6

Download GeoLite database

The platform uses GeoIP for location tracking. Download the GeoLite database:
npm run geolite:download
This script downloads the MaxMind GeoLite2 database for IP-based geolocation. The database is used to determine country and city from click IP addresses.
7

Start the backend (API)

Run the backend server in development mode:
npm run dev
The API will start on http://localhost:3333
The backend uses ts-node with --transpile-only flag for fast development reloading without type checking.
8

Start the frontend (Web)

Open a new terminal window, navigate to the web directory, and start the frontend:
cd ../web

npm install
npm run dev
The frontend will start on http://localhost:3000
9

Access the application

Open your browser and navigate to:Log in using your Google account (must match the configured domain restriction).

​
Verify Installation

Test the API health endpoint: 
curl http://localhost:3333/health
Expected response: 
{
  "status": "ok",
  "dbConnection": "healthy"
}

​
Alternative: Docker Compose (Full Stack)

You can also run both the database and API using Docker Compose: 
docker-compose up -d
This will start:
  • PostgreSQL on port 5432
  • API on port 3333
The frontend (web) is not included in Docker Compose by default. Run it separately using the steps above.

​
Common Issues

​
Port Already in Use

If you encounter port conflicts: 
# Check what's using port 3333 or 5432
lsof -i :3333
lsof -i :5432

# Kill the process or change the port in .env

​
Database Connection Failed

Ensure:
  • PostgreSQL container is running: docker ps
  • DATABASE_URL in .env matches your database configuration
  • No firewall blocking port 5432

​
Google OAuth Errors

Verify:
  • Redirect URIs in Google Cloud Console match your local URLs
  • GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are correct
  • Your email domain is allowed (check backend configuration)

​
Next Steps

Architecture

Understand the system architecture and domain model

API Reference

Explore available API endpoints

Core Features

Learn about link management and features

Deployment

Deploy to production on Vercel and Railway
Visit the Swagger documentation at http://localhost:3333/docs to explore and test API endpoints interactively.

Build docs developers (and LLMs) love

Get started for freeTalk to us