Installation Guide

This guide covers multiple installation methods for CryptoPulse, from local development to production-ready multi-instance deployments.

Prerequisites

Required Software

Node.js

Version 22 or higher required

pnpm

Package manager for local development

PostgreSQL

Version 16+ recommended

Redis

Version 7+ for coordination and throttling

Optional Software

Docker & Docker Compose: For containerized deployments
nginx: For load balancing multiple instances

External Services

You must have a CoinGecko API key. Sign up at coingecko.com/en/api. The free tier is sufficient for development.

Installation Methods

Local Development
Docker Single Instance
Docker Multi-Instance

Local Development Setup

Perfect for development and testing without containers.

Install Dependencies

Ensure Node.js 22+ and pnpm are installed:

node --version  # Should be 22 or higher
pnpm --version

If pnpm isn’t installed:

npm install -g pnpm

Clone and Install

git clone <repository-url>
cd crypto-pulse
pnpm install

Set Up Local Services

You need PostgreSQL and Redis running locally. Using Docker:

# Start only PostgreSQL and Redis
docker compose -f docker-compose.local.yml up -d

Or install them natively:

brew install postgresql@16 redis
brew services start postgresql@16
brew services start redis

# Create database
createdb crypto_pulse

Configure Environment

Copy .env.example to .env and configure for localhost:

cp .env.example .env

Edit .env:

.env

PORT=3000

ADMIN_USER=admin
ADMIN_PASS=secret
JWT_SECRET=your-secure-secret-here
JWT_EXPIRES_IN=1h

# Use localhost for local development
DATABASE_URL=postgres://postgres:postgres@localhost:5432/crypto_pulse
REDIS_URL=redis://localhost:6379

THROTTLE_TTL_MS=60000
THROTTLE_GLOBAL_LIMIT=20
THROTTLE_LOGIN_LIMIT=5

COINGECKO_BASE_URL=https://api.coingecko.com
COINGECKO_API_KEY=your-api-key-here
COINGECKO_TIMEOUT_MS=3000

BATCH_WINDOW_MS=5000
BATCH_THRESHOLD=3
REQUEST_TIMEOUT_MS=8000

LOG_LEVEL=info

Run Development Server

pnpm run start:dev

The API will start with hot-reload enabled. Access:

API: http://localhost:3000
Swagger: http://localhost:3000/docs

Development Commands

# Run with hot-reload
pnpm run start:dev

# Build for production
pnpm run build

# Run production build
pnpm run start:prod

# Run tests
pnpm run test
pnpm run test:e2e
pnpm run test:cov  # with coverage

# Lint and format
pnpm run lint
pnpm run format
pnpm run check  # lint + format

Docker Single Instance

Run everything (PostgreSQL, Redis, API) as a single stack.

Clone Repository

git clone <repository-url>
cd crypto-pulse

Configure Environment

cp .env.example .env

Edit .env and use Docker service names:

.env

PORT=3000

ADMIN_USER=admin
ADMIN_PASS=secret
JWT_SECRET=your-secure-secret-here
JWT_EXPIRES_IN=1h

# Use Docker service names for inter-container networking
DATABASE_URL=postgres://postgres:postgres@postgres:5432/crypto_pulse
REDIS_URL=redis://redis:6379

COINGECKO_API_KEY=your-api-key-here
COINGECKO_BASE_URL=https://api.coingecko.com
COINGECKO_TIMEOUT_MS=3000

BATCH_WINDOW_MS=5000
BATCH_THRESHOLD=3
REQUEST_TIMEOUT_MS=8000

LOG_LEVEL=info

Start Services

docker compose up --build

Wait for health checks:

✔ postgres  Healthy
✔ redis     Healthy
✔ api       Started

Access the API at http://localhost:3000

Docker Commands

# Start in detached mode
docker compose up -d

# View logs
docker compose logs -f api

# Restart API only
docker compose restart api

# Stop services
docker compose down

# Stop and remove volumes (deletes data)
docker compose down -v

# Rebuild after code changes
docker compose up --build

Docker Multi-Instance with Load Balancer

Production-ready setup with nginx load balancing across 2 API instances.

Clone Repository

git clone <repository-url>
cd crypto-pulse

Configure Environment

cp .env.example .env

Use the same configuration as single instance setup.

Start Multi-Instance Stack

docker compose -f docker-compose.multi.yml up --build -d

This launches:

1x PostgreSQL (shared)
1x Redis (shared)
2x API instances (api1, api2)
1x nginx load balancer

Access via Load Balancer

All requests go through nginx at http://localhost:3000nginx automatically distributes traffic between api1 and api2.

Architecture

Client → nginx:3000 → ┬→ api1:3000 ┐
                       │            ├→ postgres:5432
                       └→ api2:3000 ┘    redis:6379

Redis ensures batching coordination and throttling work correctly across both API instances. When api1 receives a request for bitcoin and api2 receives another within the batch window, they coordinate through Redis to make only one CoinGecko call.

Multi-Instance Commands

# View all services
docker compose -f docker-compose.multi.yml ps

# Logs from specific service
docker compose -f docker-compose.multi.yml logs -f api1
docker compose -f docker-compose.multi.yml logs -f nginx

# Scale to 4 instances (requires nginx config update)
docker compose -f docker-compose.multi.yml up -d --scale api=4

# Stop everything
docker compose -f docker-compose.multi.yml down -v

Environment Variables Reference

Authentication

Variable	Required	Default	Description
`ADMIN_USER`	Yes	-	Username for `/auth/login`
`ADMIN_PASS`	Yes	-	Password for `/auth/login`
`JWT_SECRET`	Yes	-	Secret for signing JWT tokens
`JWT_EXPIRES_IN`	No	`1h`	Token expiration (e.g., `1h`, `30m`, `7d`)

Database & Cache

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection string
`REDIS_URL`	Yes	-	Redis connection string

Rate Limiting

Variable	Required	Default	Description
`THROTTLE_TTL_MS`	No	`60000`	Throttle window duration in milliseconds
`THROTTLE_GLOBAL_LIMIT`	No	`20`	Max requests per window (all endpoints)
`THROTTLE_LOGIN_LIMIT`	No	`5`	Max login attempts per window

CoinGecko Integration

Variable	Required	Default	Description
`COINGECKO_API_KEY`	Yes	-	Your CoinGecko API key
`COINGECKO_BASE_URL`	No	`https://api.coingecko.com`	CoinGecko API base URL
`COINGECKO_TIMEOUT_MS`	No	`3000`	Upstream request timeout

Batching Configuration

Variable	Required	Default	Description
`BATCH_WINDOW_MS`	No	`5000`	Max time to wait before flushing batch
`BATCH_THRESHOLD`	No	`3`	Number of requests to trigger early flush
`REQUEST_TIMEOUT_MS`	No	`8000`	Max wait time per client request

Application

Variable	Required	Default	Description
`PORT`	No	`3000`	HTTP server port
`LOG_LEVEL`	No	`info`	Winston log level (`error`, `warn`, `info`, `debug`)

Database Setup

Automatic Migration

TypeORM automatically creates tables on first startup. No manual migration needed.

Manual Database Access

# Connect to PostgreSQL in Docker
docker compose exec postgres psql -U postgres -d crypto_pulse

Useful queries:

-- View all price records
SELECT * FROM price_snapshot ORDER BY fetched_at DESC LIMIT 10;

-- Count records per coin
SELECT coin_id, COUNT(*) as count 
FROM price_snapshot 
GROUP BY coin_id;

-- Clear all data
TRUNCATE TABLE price_snapshot;

Verification

After installation, verify everything works:

Check Service Health

curl http://localhost:3000/docs

Should return the Swagger HTML page.

Test Authentication

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"secret"}'

Should return a JWT token.

Test Price Endpoint

TOKEN="your-token-here"
curl http://localhost:3000/v1/price/bitcoin \
  -H "Authorization: Bearer $TOKEN"

Should return Bitcoin’s current price.

Troubleshooting

Port 3000 already in use

Change the PORT in .env to something else like 3001, then restart.

Cannot connect to PostgreSQL

Verify PostgreSQL is running:

# Docker
docker compose ps postgres

# Local
pg_isready -h localhost -p 5432

Check the DATABASE_URL format and credentials.

Cannot connect to Redis

Verify Redis is running:

# Docker
docker compose ps redis

# Local
redis-cli ping  # Should return PONG

TypeORM synchronization errors

If tables don’t auto-create, check database permissions:

GRANT ALL PRIVILEGES ON DATABASE crypto_pulse TO postgres;

CoinGecko API errors

Verify your API key is valid and has not exceeded rate limits. Check CoinGecko API status.

Next Steps

Quickstart

Follow the quickstart guide to make your first API calls

Configuration

Learn how to customize batching, throttling, and more

API Reference

Explore all available endpoints and parameters

Deployment

Production deployment best practices and scaling

Get Started

Core Concepts

Configuration

Deployment

Installation

Installation Guide

Prerequisites

Required Software

Node.js

pnpm

PostgreSQL

Redis

Optional Software

External Services

Installation Methods

Local Development Setup

Development Commands

Docker Single Instance

Docker Commands

Docker Multi-Instance with Load Balancer

Architecture

Multi-Instance Commands

Environment Variables Reference

Authentication

Database & Cache

Rate Limiting

CoinGecko Integration

Batching Configuration

Application

Database Setup

Automatic Migration

Manual Database Access

Verification

Troubleshooting

Next Steps

Quickstart

Configuration

API Reference

Deployment

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Deployment

​Installation Guide

​Prerequisites

​Required Software

Node.js

pnpm

PostgreSQL

Redis

​Optional Software

​External Services

​Installation Methods

​Local Development Setup

​Development Commands

​Docker Single Instance

​Docker Commands

​Docker Multi-Instance with Load Balancer

​Architecture

​Multi-Instance Commands

​Environment Variables Reference

​Authentication

​Database & Cache

​Rate Limiting

​CoinGecko Integration

​Batching Configuration

​Application

​Database Setup

​Automatic Migration

​Manual Database Access

​Verification

​Troubleshooting

​Next Steps

Quickstart

Configuration

API Reference

Deployment

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Required Software

Optional Software

External Services

Installation Methods

Local Development Setup

Development Commands

Docker Single Instance

Docker Commands

Docker Multi-Instance with Load Balancer

Architecture

Multi-Instance Commands

Environment Variables Reference

Authentication

Database & Cache

Rate Limiting

CoinGecko Integration

Batching Configuration

Application

Database Setup

Automatic Migration

Manual Database Access

Verification

Troubleshooting

Next Steps