Skip to main content

Installation

This guide covers setting up your local development environment to work with the Pinboard API.

Requirements​

  • Node.js 22.0.0 or higher
  • Python 3.10 or higher (for backend development)
  • PostgreSQL (or Neon for cloud database)

Frontend Setup​

If you're building a frontend that integrates with the Pinboard API:

1. Install Dependencies​

npm install
# or
yarn install

2. Configure Environment​

Create a .env.local file:

NEXT_PUBLIC_API_URL=https://api.pinboard.ai
# For local development:
# NEXT_PUBLIC_API_URL=http://localhost:8000

3. API Client Setup​

Create an API client utility:

// lib/api.ts
const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000';

export async function apiRequest<T>(
  endpoint: string,
  options: RequestInit = {}
): Promise<T> {
  const token = getAccessToken(); // Your token storage logic

  const response = await fetch(`${API_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'Authorization': token ? `Bearer ${token}` : '',
      ...options.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || 'API request failed');
  }

  return response.json();
}

Backend Development​

If you're contributing to the Pinboard backend:

1. Clone the Repository​

git clone https://github.com/pinboard/pinboard-v4.git
cd pinboard-v4

2. Set Up Python Environment​

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

3. Configure Environment​

Create a .env file in the backend directory:

DATABASE_URL=postgresql://user:password@localhost:5432/pinboard
JWT_SECRET=your-jwt-secret-here
NEXTAUTH_SECRET=same-as-frontend-secret
ALLOWED_ORIGINS=http://localhost:3000

4. Run the API Server​

uvicorn app.main:app --reload --port 8000

The API will be available at:

Testing Your Setup​

Verify your installation:

# Health check
curl http://localhost:8000/health

# Expected response:
# {"status": "healthy", "version": "1.0.0"}

Docker Setup (Optional)​

For containerized development:

# docker-compose.yml
version: '3.8'
services:
  api:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/pinboard
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=pinboard
      - POSTGRES_PASSWORD=postgres
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Run with:

docker-compose up -d

Next Steps​