Installation

Permission Mongo can be installed in multiple ways depending on your environment and preferences.

Prerequisites

Permission Mongo requires:

MongoDB 6.0+ - Document storage, versioning, audit logs
Redis 7.0+ - Policy caching, hierarchy lookups (optional but recommended)
Go 1.21+ - Only required if building from source

Redis is optional but highly recommended for production deployments. Without Redis, policies and hierarchy data will be fetched from MongoDB on every request, significantly impacting performance.

Installation methods

Docker Compose (Recommended)
Docker Image
Binary
From Source

The easiest way to get started with all dependencies included.

Multi-container setup

Run Permission Mongo, MongoDB, and Redis as separate containers:

# Clone repository
git clone https://github.com/KTS-o7/permission-mongo.git
cd permission-mongo

# Start all services
docker-compose -f docker/docker-compose.yaml up -d

# Check status
docker-compose -f docker/docker-compose.yaml ps

# View logs
docker-compose -f docker/docker-compose.yaml logs -f pm-server

This starts three containers (see docker/docker-compose.yaml:1-50):

pm-server - Permission Mongo on port 8080
mongo - MongoDB 7 on port 27017
redis - Redis 7 on port 6379

The server mounts your local config/ directory for configuration.

All-in-one container

For simpler deployments, use the all-in-one image with MongoDB + Redis + Server:

# Build all-in-one image
make docker-allinone

# Run with Docker
docker run -d --name permission-mongo \
  -p 8080:8080 -p 27017:27017 -p 6379:6379 \
  -v pm_mongo_data:/data/db \
  -v pm_redis_data:/data/redis \
  -v $(pwd)/config:/app/config:ro \
  permissionmongo/allinone:latest

# Or with Docker Compose
docker-compose -f docker/docker-compose.allinone.yaml up -d

See Makefile:60-83 for all Docker targets.

Environment variables

Override configuration with environment variables:

docker-compose.yaml

services:
  pm-server:
    environment:
      - MONGO_URI=mongodb://mongo:27017
      - MONGO_DATABASE=permission_mongo
      - REDIS_URL=redis://redis:6379
      - PM_DEV_MODE=false  # Enable for testing without JWT

These are read by the server in cmd/server/main.go:63-84.

Use the pre-built Docker image if you’re running MongoDB and Redis separately.

Pull and run

# Pull latest image
docker pull permissionmongo/server:latest

# Run server
docker run -d --name pm-server \
  -p 8080:8080 \
  -e MONGO_URI=mongodb://host.docker.internal:27017 \
  -e MONGO_DATABASE=permission_mongo \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  -v $(pwd)/config:/app/config:ro \
  permissionmongo/server:latest

# View logs
docker logs -f pm-server

Build your own image

# Clone repository
git clone https://github.com/KTS-o7/permission-mongo.git
cd permission-mongo

# Build image
make docker-build

# Or manually
docker build -t permissionmongo/server:latest -f docker/Dockerfile .

The Dockerfile uses multi-stage builds for minimal image size (see docker/Dockerfile:1-41):

Builder stage - Go 1.24 Alpine with build dependencies
Final stage - Alpine 3.19 with only the compiled binary

Final image includes:

pm-server - Main server binary built from cmd/server/main.go
pmctl - CLI management tool built from cmd/pmctl/main.go
Non-root user for security

Health checks

The Docker image includes health checks:

healthcheck:
  test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/health"]
  interval: 30s
  timeout: 5s
  retries: 3

Download pre-built binaries for your platform.

Linux

# Download latest release
curl -LO https://github.com/KTS-o7/permission-mongo/releases/latest/download/pm-server-linux-amd64

# Make executable
chmod +x pm-server-linux-amd64

# Move to PATH
sudo mv pm-server-linux-amd64 /usr/local/bin/pm-server

# Verify installation
pm-server --version

macOS

# Intel
curl -LO https://github.com/KTS-o7/permission-mongo/releases/latest/download/pm-server-darwin-amd64

# Apple Silicon
curl -LO https://github.com/KTS-o7/permission-mongo/releases/latest/download/pm-server-darwin-arm64

chmod +x pm-server-darwin-*
sudo mv pm-server-darwin-* /usr/local/bin/pm-server

Windows

# Download from releases page
Invoke-WebRequest -Uri "https://github.com/KTS-o7/permission-mongo/releases/latest/download/pm-server-windows-amd64.exe" -OutFile "pm-server.exe"

# Add to PATH or run directly
.\pm-server.exe --version

Running

Ensure MongoDB and Redis are running, then:

# Create config directory
mkdir -p config

# Add your schema.yml, policy.yml, etc.
# (See Configuration section)

# Run server
pm-server --config ./config

The server will:

Load configuration from the specified directory (see cmd/server/main.go:55-59)
Connect to MongoDB and Redis
Initialize schema validator, RBAC engine, and other components
Start HTTP server on the configured host:port

Build from source for development or to use unreleased features.

Clone and build

# Clone repository
git clone https://github.com/KTS-o7/permission-mongo.git
cd permission-mongo

# Install dependencies
go mod download

# Build binaries
make build

# Binaries created in bin/
ls -lh bin/
# bin/pm-server   - Main server
# bin/pmctl       - CLI tool

The build process (see Makefile:8-11):

Creates bin/ directory
Builds cmd/server/main.go with version info from git tags
Builds cmd/pmctl/main.go for management operations

Build options

# Production build (optimized, smaller binary)
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/pm-server ./cmd/server

# Linux build from macOS/Windows
make build-linux

# With custom version
go build -ldflags="-X main.Version=v1.0.0 -X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -o bin/pm-server ./cmd/server

See build flags in Makefile:3-5.

Run with hot reload

For development with automatic reload on code changes:

# Install Air
go install github.com/cosmtrek/air@latest

# Run with hot reload
make run-dev
# or
air

Configuration is in .air.toml.

Run tests

# Unit tests with race detector
make test

# With coverage
make test-coverage
# Opens coverage.html in browser

# Integration tests (requires running MongoDB/Redis)
make test-integration

# Benchmarks
make bench

See test targets in Makefile:18-29.

Configuration files

Permission Mongo requires configuration files in YAML format. The config directory should contain:

config/
├── config.example.yaml  # Server, MongoDB, Redis settings
├── schema.yml          # Collection definitions
├── policy.yml          # RBAC policies
└── hooks.yml           # Pre/post operation hooks (optional)

Minimal configuration

Create config/config.example.yaml:

config/config.example.yaml

server:
  host: "0.0.0.0"
  port: 8080

mongodb:
  uri: "mongodb://localhost:27017"
  database: "permission_mongo"

redis:
  addr: "localhost:6379"
  password: ""
  db: 0

auth:
  jwt_secret: "your-secret-key-change-in-production"
  token_expiry: "24h"

See the full example in config/config.example.yaml:1-70.

Schema definition

Create config/schema.yml with at least one collection:

config/schema.yml

version: "1.0"

settings:
  auto_timestamps: true
  id_type: objectId

collections:
  users:
    fields:
      _id: { type: objectId, auto: true }
      email: { type: string, required: true }
      name: { type: string, required: true }
      created_at: { type: date, auto: true }
    
    indexes:
      - fields: [email]
        unique: true

See complete schema examples in examples/config/schema.yml.

Policy definition

Create config/policy.yml to define access control:

config/policy.yml

version: "1.0"

roles:
  admin:
    description: "Full access"
  
  user:
    description: "Standard user"

policies:
  users:
    admin:
      actions: [create, read, update, delete]
      when: "true"  # Admins can access all
    
    user:
      actions: [read, update]
      when: doc._id == user.id  # Users can only access themselves

defaults:
  deny_all: true

See policy examples in examples/config/policy.yml.

Running the server

Command-line options

Usage: pm-server [options]

Options:
  --config <dir>     Path to configuration directory (default: ./config)
  --version          Show version and exit
  --help             Show this help message

See flag parsing in cmd/server/main.go:31-34.

Starting the server

# With default config directory
pm-server

# With custom config directory
pm-server --config /etc/permission-mongo

# Check version
pm-server --version
# Output:
# Permission Mongo Server
# Version: v1.0.0
# Build Time: 2026-03-04T12:00:00Z

The server outputs startup logs showing:

Configuration loading
MongoDB connection
Redis connection
Component initialization (schema, RBAC, hooks, etc.)
HTTP server start

Example output from cmd/server/main.go:41-200:

Permission Mongo Server
Version: v1.0.0
Loading configuration from: ./config
Connecting to MongoDB...
MongoDB connected successfully
Connecting to Redis...
Redis connected successfully
Initializing schema validator...
Initializing hierarchy resolver...
Initializing RBAC engine...
Initializing version manager...
Initializing audit logger...
Initializing API handlers...
Starting HTTP server on 0.0.0.0:8080
Server ready - all handlers initialized

Production deployment

Systemd service (Linux)

Create /etc/systemd/system/permission-mongo.service:

[Unit]
Description=Permission Mongo Server
After=network.target mongodb.service redis.service

[Service]
Type=simple
User=pmongo
Group=pmongo
WorkingDirectory=/opt/permission-mongo
ExecStart=/usr/local/bin/pm-server --config /etc/permission-mongo/config
Restart=on-failure
RestartSec=5

# Environment
Environment="MONGO_URI=mongodb://localhost:27017"
Environment="MONGO_DATABASE=permission_mongo"
Environment="REDIS_URL=redis://localhost:6379"

# Security
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/permission-mongo

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable permission-mongo
sudo systemctl start permission-mongo
sudo systemctl status permission-mongo

Kubernetes deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: permission-mongo
spec:
  replicas: 3
  selector:
    matchLabels:
      app: permission-mongo
  template:
    metadata:
      labels:
        app: permission-mongo
    spec:
      containers:
      - name: pm-server
        image: permissionmongo/server:latest
        ports:
        - containerPort: 8080
        env:
        - name: MONGO_URI
          valueFrom:
            secretKeyRef:
              name: pm-secrets
              key: mongo-uri
        - name: REDIS_URL
          valueFrom:
            secretKeyRef:
              name: pm-secrets
              key: redis-url
        volumeMounts:
        - name: config
          mountPath: /app/config
          readOnly: true
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
      volumes:
      - name: config
        configMap:
          name: pm-config
---
apiVersion: v1
kind: Service
metadata:
  name: permission-mongo
spec:
  selector:
    app: permission-mongo
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

Environment variables

All configuration can be overridden with environment variables:

Variable	Description	Default
`MONGO_URI`	MongoDB connection string	`mongodb://localhost:27017`
`MONGO_DATABASE`	Database name	`permission_mongo`
`REDIS_URL`	Redis connection URL	`redis://localhost:6379`
`PM_DEV_MODE`	Enable dev mode (no auth)	`false`
`PM_DEV_TENANT_ID`	Default tenant ID in dev mode	`000000000000000000000001`

See environment variable handling in cmd/server/main.go:63-84.

Monitoring setup

Permission Mongo exposes Prometheus metrics on /metrics.

Prometheus configuration

Add to prometheus.yml:

scrape_configs:
  - job_name: 'permission-mongo'
    static_configs:
      - targets: ['localhost:8080']
    metrics_path: /metrics
    scrape_interval: 15s

Grafana dashboard

Import the pre-built dashboard:

# Start monitoring stack
docker-compose -f docker-compose.monitoring.yaml up -d

# Access Grafana at http://localhost:3000
# Default credentials: admin/admin

The dashboard is located in monitoring/grafana/dashboards/permission-mongo.json. Available metrics (from README.md:164-177):

permission_mongo_http_requests_total - Request counts
permission_mongo_http_request_duration_seconds - Latency
permission_mongo_mongo_operations_total - MongoDB ops
permission_mongo_cache_hits_total / cache_misses_total - Cache performance
permission_mongo_rbac_evaluations_total - RBAC decisions

See full monitoring documentation in monitoring/README.md.

Upgrading

Binary upgrade

# Download new version
curl -LO https://github.com/KTS-o7/permission-mongo/releases/download/v1.1.0/pm-server-linux-amd64

# Stop server
sudo systemctl stop permission-mongo

# Replace binary
sudo mv pm-server-linux-amd64 /usr/local/bin/pm-server
sudo chmod +x /usr/local/bin/pm-server

# Start server
sudo systemctl start permission-mongo

Docker upgrade

# Pull new image
docker pull permissionmongo/server:v1.1.0

# Update docker-compose.yaml to use new tag
# Then restart
docker-compose -f docker/docker-compose.yaml up -d

Database migrations

Permission Mongo does not require schema migrations. Configuration changes in schema.yml and policy.yml are applied automatically on server restart (hot reload is supported).

Next steps

Quickstart

Make your first API call in 5 minutes

Architecture

Understand the system components and data flow

Configuration

Learn how to configure schema, policies, and hooks

Production Best Practices

Security, performance, and reliability recommendations

Getting Started

Core Concepts

Configuration

Guides

Monitoring & Observability

Advanced

SDK

​Installation

​Prerequisites

​Installation methods

​Multi-container setup

​All-in-one container

​Environment variables

​Pull and run

​Build your own image

​Health checks

​Linux

​macOS

​Windows

​Running

​Clone and build

​Build options

​Run with hot reload

​Run tests

​Configuration files

​Minimal configuration

​Schema definition

​Policy definition

​Running the server

​Command-line options

​Starting the server

​Production deployment

​Systemd service (Linux)

​Kubernetes deployment

​Environment variables

​Monitoring setup

​Prometheus configuration

​Grafana dashboard

​Upgrading

​Binary upgrade

​Docker upgrade

​Database migrations

​Next steps

Quickstart

Architecture

Configuration

Production Best Practices

Build docs developers (and LLMs) love

Installation

Prerequisites

Installation methods

Multi-container setup

All-in-one container

Environment variables

Pull and run

Build your own image

Health checks

Linux

macOS

Windows

Running

Clone and build

Build options

Run with hot reload

Run tests

Configuration files

Minimal configuration

Schema definition

Policy definition

Running the server

Command-line options

Starting the server

Production deployment

Systemd service (Linux)

Kubernetes deployment

Environment variables

Monitoring setup

Prometheus configuration

Grafana dashboard

Upgrading

Binary upgrade

Docker upgrade

Database migrations

Next steps