Recipe Registry Server

Deploy and manage HTTP recipe registry servers

The Recipe Registry Server provides an HTTP interface for sharing recipes across teams and organizations. It supports token-based authentication, read-only mode, and can be deployed locally or on cloud infrastructure.

praisonai serve registry is the canonical command. The legacy praisonai registry serve form is deprecated (prints a warning to stderr) and its default port is now 7777 — aligned with this form. Update any old scripts or Dockerfiles that relied on the old 8080 default. See the Registry CLI for details.

Quick Start

# Start registry server on default port (7777)
praisonai serve registry

# Start with authentication
praisonai serve registry --token mysecrettoken

# Start on custom port
praisonai serve registry --port 8080

# Check server status
praisonai registry status

Server Configuration

Basic Server

praisonai serve registry [options]

Option	Default	Description
--host	127.0.0.1	Host to bind to
--port	7777	Port to bind to
--dir	~/.praisonai/registry	Registry directory
--token	None	Require token for write operations
--read-only	false	Disable all write operations
--json	false	Output in JSON format

Authentication

Enable token authentication to protect write operations:

# Start with token authentication
praisonai serve registry --token $PRAISONAI_REGISTRY_TOKEN

# Clients must provide token for publish/delete
praisonai recipe publish ./my-recipe \
  --registry http://localhost:7777 \
  --token $PRAISONAI_REGISTRY_TOKEN

Read-Only Mode

Deploy a read-only registry for public access:

# Start in read-only mode
praisonai serve registry --read-only

# Clients can pull and list, but not publish
praisonai recipe pull my-recipe --registry http://localhost:7777

Programmatic Server

Start the server programmatically in Python:

from praisonai.recipe.server import run_server
from pathlib import Path

# Start server (blocking)
run_server(
    host="127.0.0.1",
    port=7777,
    registry_path=Path("~/.praisonai/registry").expanduser(),
    token="optional-auth-token",
    read_only=False
)

WSGI Application

Get the WSGI app for custom deployment:

from praisonai.recipe.server import create_wsgi_app
from pathlib import Path

# Create WSGI app
app = create_wsgi_app(
    registry_path=Path("~/.praisonai/registry").expanduser(),
    token="optional-token",
    read_only=False
)

# Deploy with gunicorn, uwsgi, etc.

Health Check

Check server status:

# CLI
praisonai registry status --registry http://localhost:7777

# curl
curl http://localhost:7777/healthz

Response:

{
  "status": "healthy",
  "auth_required": true,
  "read_only": false,
  "version": "1.0.0"
}

Deployment Options

Local Development

# Simple local server
praisonai serve registry --port 7777

Docker

FROM python:3.11-slim

RUN pip install praisonai

EXPOSE 7777

CMD ["praisonai", "serve", "registry", "--host", "0.0.0.0", "--port", "7777"]

docker build -t praisonai-registry .
docker run -p 7777:7777 -v ~/.praisonai/registry:/root/.praison/registry praisonai-registry

Docker Compose

version: '3.8'
services:
  registry:
    image: praisonai-registry
    ports:
      - "7777:7777"
    volumes:
      - registry-data:/root/.praison/registry
    environment:
      - PRAISONAI_REGISTRY_TOKEN=${REGISTRY_TOKEN}
    command: >
      praisonai serve registry 
      --host 0.0.0.0 
      --port 7777 
      --token ${REGISTRY_TOKEN}

volumes:
  registry-data:

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: recipe-registry
spec:
  replicas: 1
  selector:
    matchLabels:
      app: recipe-registry
  template:
    metadata:
      labels:
        app: recipe-registry
    spec:
      containers:
      - name: registry
        image: praisonai-registry:latest
        ports:
        - containerPort: 7777
        env:
        - name: PRAISONAI_REGISTRY_TOKEN
          valueFrom:
            secretKeyRef:
              name: registry-secrets
              key: token
        volumeMounts:
        - name: registry-data
          mountPath: /root/.praison/registry
      volumes:
      - name: registry-data
        persistentVolumeClaim:
          claimName: registry-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: recipe-registry
spec:
  selector:
    app: recipe-registry
  ports:
  - port: 7777
    targetPort: 7777
  type: ClusterIP

Behind Nginx

upstream registry {
    server 127.0.0.1:7777;
}

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

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

    location / {
        proxy_pass http://registry;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # For large bundle uploads
        client_max_body_size 100M;
    }
}

Security Best Practices

Token Management

# Generate a secure token
export PRAISONAI_REGISTRY_TOKEN=$(openssl rand -hex 32)

# Start server with token
praisonai serve registry --token $PRAISONAI_REGISTRY_TOKEN

Network Security

• Local only: Bind to 127.0.0.1 for local-only access
• Firewall: Restrict port access to trusted IPs
• TLS: Use nginx/traefik for HTTPS termination
• VPN: Deploy within private network

Access Control

Mode	Read	Write	Delete
No token	✓	✓	✓
With token	✓	Token required	Token required
Read-only	✓	✗	✗

Monitoring

Logs

Server logs include:

• Request method and path
• Response status codes
• Authentication attempts
• Error details

Metrics

Monitor these endpoints:

• GET /healthz - Health check
• GET /v1/recipes - Recipe count

Environment Variables

Variable	Description
PRAISONAI_REGISTRY_TOKEN	Default authentication token
PRAISONAI_REGISTRY_PATH	Default registry directory

Troubleshooting

Port Already in Use

# Find process using port
lsof -i :7777

# Use different port
praisonai serve registry --port 7778

Permission Denied

# Check directory permissions
ls -la ~/.praisonai/registry

# Create directory if needed
mkdir -p ~/.praisonai/registry

Authentication Errors

# Verify token is set
echo $PRAISONAI_REGISTRY_TOKEN

# Test with curl
curl -H "Authorization: Bearer $TOKEN" http://localhost:7777/healthz

Related

• Recipe Registry - Python API reference
• Recipe Registry API - HTTP API endpoints
• Recipe CLI - CLI commands