Skip to main content
Deploy Osmedeus as a server or in distributed mode.

​
Single Server

​
Start the Server

# Default configuration
osmedeus server

# Custom host and port
osmedeus server --host 0.0.0.0 --port 8080

# Disable authentication (development only)
osmedeus server -A
The server provides:
  • REST API at http://localhost:8002/osm/api/
  • Swagger docs at http://localhost:8002/swagger/
  • Health check at http://localhost:8002/health
  • Web UI at http://localhost:8002/ (if configured)

​
Authentication

Default credentials (change in osm-settings.yaml):
  • Username: osmedeus
  • Password: osmedeus-admin
Get a JWT token: 
curl -X POST http://localhost:8002/osm/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "osmedeus", "password": "osmedeus-admin"}'
Use the token in subsequent requests: 
curl http://localhost:8002/osm/api/workflows \
  -H "Authorization: Bearer <token>"

​
Distributed Mode

Scale scanning across multiple machines using Redis for coordination.

​
Architecture

┌─────────────────┐     ┌─────────────────┐
│     Master      │     │     Redis       │
│   (API Server)  │────▶│   (Task Queue)  │
└─────────────────┘     └────────┬────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        │                        │                        │
        ▼                        ▼                        ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│   Worker 1    │       │   Worker 2    │       │   Worker N    │
└───────────────┘       └───────────────┘       └───────────────┘

​
Start Master

# Start master with default Redis (localhost:6379)
osmedeus server --master

# Custom Redis URL
osmedeus server --master --redis-url redis://redis-host:6379

​
Start Workers

On each worker machine: 
# Join as worker
osmedeus worker join

# Custom Redis URL
osmedeus worker join --redis-url redis://redis-host:6379

​
Submit Distributed Scans

# Submit to distributed queue
osmedeus run -f general -t example.com -D

# With custom Redis
osmedeus run -f general -t example.com -D --redis-url redis://redis-host:6379

​
Monitor Status

# Check worker status
osmedeus worker status
Via API: 
# List workers
curl http://master:8002/osm/api/workers -H "Authorization: Bearer <token>"

# List tasks
curl http://master:8002/osm/api/tasks -H "Authorization: Bearer <token>"

​
Docker Deployment

​
Single Container

# Build image
docker build -t osmedeus:latest -f build/docker/Dockerfile .

# Run container
docker run -d \
  --name osmedeus \
  -p 8002:8002 \
  -v osmedeus-data:/root/osmedeus-base \
  osmedeus:latest

​
Docker Compose (Distributed)

Create docker-compose.yml: 
version: '3.8'

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  master:
    build:
      context: .
      dockerfile: build/docker/Dockerfile
    command: osmedeus server --master
    ports:
      - "8002:8002"
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
    volumes:
      - master-data:/root/osmedeus-base

  worker:
    build:
      context: .
      dockerfile: build/docker/Dockerfile
    command: osmedeus worker join
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
      - master
    deploy:
      replicas: 3

volumes:
  master-data:
Run: 
# Start services
docker-compose up -d

# Scale workers
docker-compose up -d --scale worker=5

# View logs
docker-compose logs -f master
docker-compose logs -f worker

​
Production Considerations

​
Security

  1. Change default credentials in osm-settings.yaml
  2. Use HTTPS - Put behind a reverse proxy (nginx, Caddy)
  3. Restrict network access - Firewall rules for Redis and API
  4. Use secrets management - Environment variables for passwords

​
Reverse Proxy (nginx)

server {
    listen 443 ssl;
    server_name osmedeus.example.com;

    ssl_certificate /etc/ssl/certs/osmedeus.crt;
    ssl_certificate_key /etc/ssl/private/osmedeus.key;

    location / {
        proxy_pass http://localhost:8002;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

​
Resource Limits

In Docker Compose: 
worker:
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 4G

​
Persistence

  • Mount volumes for /root/osmedeus-base
  • Use external Redis with persistence
  • Consider PostgreSQL for production

​
Next Steps