> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# CLI
praisonai registry status --registry http://localhost:7777

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

**Response:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "status": "healthy",
  "auth_required": true,
  "read_only": false,
  "version": "1.0.0"
}
```

## Deployment Options

### Local Development

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple local server
praisonai serve registry --port 7777
```

### Docker

```dockerfile theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
FROM python:3.11-slim

RUN pip install praisonai

EXPOSE 7777

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
docker build -t praisonai-registry .
docker run -p 7777:7777 -v ~/.praisonai/registry:/root/.praison/registry praisonai-registry
```

### Docker Compose

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```nginx theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Find process using port
lsof -i :7777

# Use different port
praisonai serve registry --port 7778
```

### Permission Denied

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Check directory permissions
ls -la ~/.praisonai/registry

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

### Authentication Errors

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Verify token is set
echo $PRAISONAI_REGISTRY_TOKEN

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

## Related

* [Recipe Registry](/docs/features/recipe-registry) - Python API reference
* [Recipe Registry API](/docs/deploy/api/recipe-registry-api) - HTTP API endpoints
* [Recipe CLI](/docs/cli/recipe-registry) - CLI commands