Skip to content

Installation.md

Latest commit

 

History

History
308 lines (222 loc) · 5.89 KB

Installation.md

File metadata and controls

308 lines (222 loc) · 5.89 KB
title Installation Manual
description Complete guide to install and configure OSM Notes API.
version 1.0.0
last_updated 2026-01-25
author AngocA
tags
installation
audience
developers
project OSM-Notes-API
status active

Installation Manual

Complete guide to install and configure OSM Notes API.

Prerequisites

Required Software

  • Node.js: >= 18.0.0
  • npm: >= 9.0.0 (or equivalent yarn/pnpm)
  • PostgreSQL: >= 15.0
  • Redis: >= 7.0 (optional but recommended)

Database Access

The API requires access to the Analytics database:

  • Database: osm_notes_dwh
  • Schema: dwh (datamarts)
  • User: With read permissions on dwh schema
  • Foreign Data Wrappers: If databases are separate, FDWs must be configured

Infrastructure

  • Server: Recommended 2-4 CPU cores, 4GB RAM minimum
  • Network: Low latency to PostgreSQL (< 5ms ideal)

Local Installation

1. Clone Repository

git clone https://github.com/OSM-Notes/OSM-Notes-API.git
cd OSM-Notes-API

2. Install Dependencies

npm install

3. Configure Environment Variables

cp .env.example .env

Edit .env with your configurations:

# Server
NODE_ENV=development
PORT=3000

# Database
DB_HOST=192.168.0.7
DB_PORT=5432
DB_NAME=osm_notes_dwh
DB_USER=analytics_user
DB_PASSWORD=your_password_here

# Redis
REDIS_HOST=192.168.0.7
REDIS_PORT=6379
REDIS_PASSWORD=

# Logging
LOG_LEVEL=info

4. Build TypeScript

npm run build

5. Verify Installation

# Verify types
npm run type-check

# Run tests (requires test database)
npm test

# Run tests with coverage report
npm run test:coverage

# Run only unit tests
npm run test:unit

# Run only integration tests
npm run test:integration

# Verify formatting
npm run format:check

Note: Integration tests require a test database. By default, tests use:

  • Database: osm_notes_api_test
  • User: osm_notes_test_user
  • Password: osm_notes_test_pass

To set up the test database, create the user and database in PostgreSQL:

CREATE USER osm_notes_test_user WITH PASSWORD 'osm_notes_test_pass';
ALTER USER osm_notes_test_user CREATEDB;
CREATE DATABASE osm_notes_api_test OWNER osm_notes_test_user;
GRANT ALL PRIVILEGES ON DATABASE osm_notes_api_test TO osm_notes_test_user;

You can override these defaults by setting environment variables:

export DB_NAME=your_test_db
export DB_USER=your_test_user
export DB_PASSWORD=your_test_password

6. Start Application

# Production (default port 3000)
npm start

# Use a different port (e.g. when 3000 is in use)
PORT=3010 npm start

# Development (with hot reload)
npm run dev

The API will be available at http://localhost:3000 (or http://localhost:3010 if you set PORT=3010).

Docker Installation

Requirements

  • Docker >= 20.10
  • Docker Compose >= 2.0

Steps

  1. Configure environment variables:

    cp .env.example .env
# Edit .env

  2. Start services:

    docker compose -f docker/docker compose.yml up -d

  3. Verify everything is running:

    docker compose -f docker/docker compose.yml ps
docker compose -f docker/docker compose.yml logs api

  4. Health check:

    curl http://localhost:3000/health

See docker/README.md for more Docker details.

Installation Verification

Health Check

curl http://localhost:3000/health

Expected response:

{
  "status": "ok",
  "database": "connected",
  "redis": "connected",
  "timestamp": "2025-12-14T10:00:00.000Z"
}

Database Connection Test

# From container or server
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT COUNT(*) FROM dwh.datamartUsers LIMIT 1;"

Redis Connection Test

redis-cli -h $REDIS_HOST -p $REDIS_PORT ping

Advanced Configuration

Complete Environment Variables

See .env.example for all available variables:

  • Server: PORT, NODE_ENV, API_VERSION
  • Database: DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_SSL
  • Redis: REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_DB
  • Rate Limiting: RATE_LIMIT_WINDOW_MS, RATE_LIMIT_MAX_REQUESTS
  • OAuth: OAUTH_ENABLED, OSM_OAUTH_CLIENT_ID, OSM_OAUTH_CLIENT_SECRET
  • Logging: LOG_LEVEL, LOG_FORMAT
  • Metrics: METRICS_ENABLED, METRICS_PORT
  • Documentation: API_DOCS_ENABLED, API_DOCS_PATH

External Database Configuration

If the database is on a remote server:

  1. Ensure PostgreSQL allows remote connections
  2. Configure firewall to allow connections from API server
  3. Use SSL if possible: 
    DB_SSL=true

External Redis Configuration

If Redis is on a remote server:

  1. Configure Redis to accept remote connections
  2. Configure password if necessary: 
    REDIS_PASSWORD=your_secure_password

Troubleshooting

Database Connection Error

# Verify PostgreSQL is running
systemctl status postgresql

# Verify connection
psql -h $DB_HOST -U $DB_USER -d $DB_NAME

# Verify user permissions
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "\du"

Redis Connection Error

# Verify Redis is running
redis-cli ping

# Verify configuration
redis-cli CONFIG GET requirepass

Port Already in Use

# See what process is using port 3000
lsof -i :3000

# Change port in .env
PORT=3001

Permission Issues

# Verify file permissions
ls -la

# Adjust if necessary
chmod +x scripts/*

Next Steps

Once installed:

  1. Read docs/USAGE.md to learn how to use the API
  2. Review docs/api/ for complete endpoint documentation
  3. Check CONTRIBUTING.md if you want to contribute

Support

If you encounter problems during installation:

  1. Review logs: npm run dev or docker compose logs
  2. Verify all requirements are met
  3. Open an issue on GitHub with problem details