doorman/user-docs/01-getting-started.md

Getting Started

Prerequisites

• Docker and Docker Compose OR Python 3.11+ and Node 20+
• Optional: Redis and MongoDB (production)

Quick Start

# Clone the repository
git clone https://github.com/apidoorman/doorman.git
cd doorman

# Copy and edit .env
cp .env.example .env
# Set: DOORMAN_ADMIN_EMAIL, DOORMAN_ADMIN_PASSWORD, JWT_SECRET_KEY

# Start
docker compose up

Access: Backend http://localhost:3001, Web UI http://localhost:3000

Environment Variables

Minimal .env configuration:

# Required
DOORMAN_ADMIN_EMAIL=admin@example.com
DOORMAN_ADMIN_PASSWORD=YourStrongPassword123!
JWT_SECRET_KEY=change-this-to-a-strong-secret-key

# Mode
MEM_OR_EXTERNAL=MEM  # MEM for dev, REDIS for production
THREADS=1  # Must be 1 in MEM mode

# Optional (production)
HTTPS_ONLY=true
REDIS_HOST=localhost
MONGO_DB_HOSTS=localhost:27017

See Configuration Reference for all options.

First Login

export BASE=http://localhost:3001
export COOKIE=/tmp/doorman.cookies

# Login
curl -sc "$COOKIE" -H 'Content-Type: application/json' \
  -d "{\"email\":\"$DOORMAN_ADMIN_EMAIL\",\"password\":\"$DOORMAN_ADMIN_PASSWORD\"}" \
  "$BASE/platform/authorization"

Or use Web UI at http://localhost:3000

Your First API

1. Create Token Group

curl -sb "$COOKIE" -H 'Content-Type: application/json' -X POST \
  "$BASE/platform/credit" \
  -d '{
    "api_credit_group": "demo-api",
    "api_key": "demo-secret-key-123",
    "api_key_header": "x-api-key",
    "credit_tiers": [
      {
        "tier_name": "default",
        "credits": 999999,
        "input_limit": 0,
        "output_limit": 0,
        "reset_frequency": "monthly"
      }
    ]
  }'

2. Create API

curl -sb "$COOKIE" -H 'Content-Type: application/json' -X POST \
  "$BASE/platform/api" \
  -d '{
    "api_name": "demo",
    "api_version": "v1",
    "api_description": "Demo API for testing",
    "api_allowed_roles": ["admin"],
    "api_allowed_groups": ["ALL"],
    "api_servers": ["http://httpbin.org"],
    "api_type": "REST",
    "api_allowed_retry_count": 0,
    "api_allowed_headers": ["content-type", "accept"],
    "api_credits_enabled": true,
    "api_credit_group": "demo-api"
  }'

3. Add Endpoints

curl -sb "$COOKIE" -H 'Content-Type: application/json' -X POST \
  "$BASE/platform/endpoint" \
  -d '{
    "api_name": "demo",
    "api_version": "v1",
    "endpoint_method": "GET",
    "endpoint_uri": "/get",
    "endpoint_description": "Echo GET request"
  }'

curl -sb "$COOKIE" -H 'Content-Type: application/json' -X POST \
  "$BASE/platform/endpoint" \
  -d '{
    "api_name": "demo",
    "api_version": "v1",
    "endpoint_method": "POST",
    "endpoint_uri": "/post",
    "endpoint_description": "Echo POST request"
  }'

4. Subscribe User

curl -sb "$COOKIE" -H 'Content-Type: application/json' -X POST \
  "$BASE/platform/subscription/subscribe" \
  -d '{
    "username": "admin",
    "api_name": "demo",
    "api_version": "v1"
  }'

5. Test

curl -sb "$COOKIE" "$BASE/api/rest/demo/v1/get?test=123"

Next Steps

• Configuration Reference - All environment variables
• Security Guide - Production hardening
• API Workflows - Real-world examples

---

Production Setup

.env Configuration

ENV=production
HTTPS_ONLY=true
MEM_OR_EXTERNAL=REDIS

# Strong secrets (required)
JWT_SECRET_KEY=<strong-random-secret-32-chars>
TOKEN_ENCRYPTION_KEY=<strong-random-secret>
MEM_ENCRYPTION_KEY=<strong-random-secret>

# CORS
ALLOWED_ORIGINS=https://yourdomain.com
CORS_STRICT=true
COOKIE_DOMAIN=yourdomain.com

# Redis/MongoDB
REDIS_HOST=redis
MONGO_DB_HOSTS=mongo:27017

Start with Redis/MongoDB

docker compose --profile production up -d

Checklist

• ENV=production and HTTPS_ONLY=true
• Change all default secrets
• Set CORS_STRICT=true with explicit origins
• TLS at reverse proxy (Nginx/Traefik/ALB)
• Change admin password after first login

See Security Guide for full hardening details