Deployment Guide

Deploy your own QuantumLock™ API instance.

Overview

QuantumLock can be deployed in multiple ways:

SaaS: Use our managed service at https://api.softquantus.com (recommended)
Self-Hosted: Deploy on your own infrastructure (Docker, Kubernetes)
Hybrid: Use SDK offline validation with SaaS license generation

Docker Deployment

Quick Start

# Clone repository
git clone https://github.com/softquantus/quantumlock-api.git
cd quantumlock-api

# Configure environment
cp .env.example .env
nano .env  # Edit configuration

# Start services
docker-compose up -d

docker-compose.yml

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: quantumlock
      POSTGRES_USER: quantumlock
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U quantumlock"]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    image: softquantus/quantumlock-api:latest
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://quantumlock:${DB_PASSWORD}@postgres:5432/quantumlock
      SECRET_KEY: ${SECRET_KEY}
      QCOS_API_URL: ${QCOS_API_URL}
      QCOS_API_KEY: ${QCOS_API_KEY}
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - api

volumes:
  postgres_data:

Environment Variables

Create .env file:

# Database
DB_PASSWORD=your_secure_password

# API Security
SECRET_KEY=your_secret_key_min_32_chars

# QCOS Integration (for quantum license generation)
QCOS_API_URL=https://api.qcos.example.com
QCOS_API_KEY=your_qcos_api_key

# Optional
LOG_LEVEL=INFO
CORS_ORIGINS=https://yourdomain.com

Generate secure keys:

# Generate SECRET_KEY
python -c "import secrets; print(secrets.token_urlsafe(32))"

# Generate DB_PASSWORD
python -c "import secrets; print(secrets.token_urlsafe(24))"

SSL/TLS Configuration

nginx.conf:

events {
    worker_connections 1024;
}

http {
    upstream api {
        server api:8000;
    }

    server {
        listen 80;
        server_name yourdomain.com;
        return 301 https://$server_name$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name yourdomain.com;

        ssl_certificate /etc/nginx/ssl/cert.pem;
        ssl_certificate_key /etc/nginx/ssl/key.pem;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;

        location / {
            proxy_pass http://api;
            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;
        }
    }
}

Kubernetes Deployment

Namespace

apiVersion: v1
kind: Namespace
metadata:
  name: quantumlock

Secrets

apiVersion: v1
kind: Secret
metadata:
  name: quantumlock-secrets
  namespace: quantumlock
type: Opaque
stringData:
  db-password: your_secure_password
  secret-key: your_secret_key
  qcos-api-key: your_qcos_api_key

PostgreSQL

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
  namespace: quantumlock
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:15-alpine
        ports:
        - containerPort: 5432
        env:
        - name: POSTGRES_DB
          value: quantumlock
        - name: POSTGRES_USER
          value: quantumlock
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: quantumlock-secrets
              key: db-password
        volumeMounts:
        - name: postgres-data
          mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
  - metadata:
      name: postgres-data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 10Gi
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: quantumlock
spec:
  selector:
    app: postgres
  ports:
  - port: 5432

API Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: quantumlock-api
  namespace: quantumlock
spec:
  replicas: 3
  selector:
    matchLabels:
      app: quantumlock-api
  template:
    metadata:
      labels:
        app: quantumlock-api
    spec:
      containers:
      - name: api
        image: softquantus/quantumlock-api:latest
        ports:
        - containerPort: 8000
        env:
        - name: DATABASE_URL
          value: postgresql://quantumlock:$(DB_PASSWORD)@postgres:5432/quantumlock
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: quantumlock-secrets
              key: db-password
        - name: SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: quantumlock-secrets
              key: secret-key
        - name: QCOS_API_KEY
          valueFrom:
            secretKeyRef:
              name: quantumlock-secrets
              key: qcos-api-key
        - name: QCOS_API_URL
          value: https://api.qcos.example.com
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: quantumlock-api
  namespace: quantumlock
spec:
  selector:
    app: quantumlock-api
  ports:
  - port: 80
    targetPort: 8000
  type: ClusterIP

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: quantumlock-ingress
  namespace: quantumlock
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - api.yourdomain.com
    secretName: quantumlock-tls
  rules:
  - host: api.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: quantumlock-api
            port:
              number: 80

Deploy

# Create namespace
kubectl apply -f namespace.yaml

# Create secrets
kubectl apply -f secrets.yaml

# Deploy PostgreSQL
kubectl apply -f postgres.yaml

# Deploy API
kubectl apply -f deployment.yaml

# Configure Ingress
kubectl apply -f ingress.yaml

# Check status
kubectl get pods -n quantumlock
kubectl logs -f deployment/quantumlock-api -n quantumlock

Cloud Deployments

AWS (ECS + RDS)

# Create RDS instance
aws rds create-db-instance \
  --db-instance-identifier quantumlock-db \
  --db-instance-class db.t3.micro \
  --engine postgres \
  --master-username quantumlock \
  --master-user-password YOUR_PASSWORD \
  --allocated-storage 20

# Create ECS cluster
aws ecs create-cluster --cluster-name quantumlock

# Create task definition
aws ecs register-task-definition --cli-input-json file://task-definition.json

# Create service
aws ecs create-service \
  --cluster quantumlock \
  --service-name quantumlock-api \
  --task-definition quantumlock-api \
  --desired-count 2 \
  --launch-type FARGATE

Azure (Container Apps + PostgreSQL)

# Create resource group
az group create --name quantumlock-rg --location eastus

# Create PostgreSQL
az postgres flexible-server create \
  --resource-group quantumlock-rg \
  --name quantumlock-db \
  --admin-user quantumlock \
  --admin-password YOUR_PASSWORD

# Create Container App environment
az containerapp env create \
  --name quantumlock-env \
  --resource-group quantumlock-rg \
  --location eastus

# Deploy container app
az containerapp create \
  --name quantumlock-api \
  --resource-group quantumlock-rg \
  --environment quantumlock-env \
  --image softquantus/quantumlock-api:latest \
  --target-port 8000 \
  --ingress external \
  --env-vars \
    DATABASE_URL=secretref:db-url \
    SECRET_KEY=secretref:secret-key

GCP (Cloud Run + Cloud SQL)

# Create Cloud SQL instance
gcloud sql instances create quantumlock-db \
  --database-version=POSTGRES_15 \
  --tier=db-f1-micro \
  --region=us-central1

# Deploy to Cloud Run
gcloud run deploy quantumlock-api \
  --image softquantus/quantumlock-api:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --add-cloudsql-instances quantumlock-db \
  --set-env-vars DATABASE_URL="postgresql://..." \
  --set-env-vars SECRET_KEY="..."

Monitoring

Prometheus + Grafana

Add metrics endpoint to your deployment:

# prometheus.yaml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'quantumlock-api'
    static_configs:
      - targets: ['quantumlock-api:8000']

Health Checks

# API health
curl https://api.yourdomain.com/health

# Database connection
curl https://api.yourdomain.com/health/db

# Quantum backend status
curl https://api.yourdomain.com/health/quantum

Logging

Configure structured logging:

# config.py
LOGGING = {
    'version': 1,
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'formatter': 'json',
        },
    },
    'formatters': {
        'json': {
            'class': 'pythonjsonlogger.jsonlogger.JsonFormatter',
        },
    },
    'root': {
        'level': 'INFO',
        'handlers': ['console'],
    },
}

Backup & Recovery

Database Backup

# Manual backup
docker exec postgres pg_dump -U quantumlock quantumlock > backup.sql

# Automated daily backups
0 2 * * * docker exec postgres pg_dump -U quantumlock quantumlock | gzip > /backups/quantumlock-$(date +\%Y\%m\%d).sql.gz

Restore

# Restore from backup
docker exec -i postgres psql -U quantumlock quantumlock < backup.sql

Security Best Practices

1. Use HTTPS Only

Always use SSL/TLS certificates
Redirect HTTP to HTTPS
Use Let's Encrypt for free certificates

2. Secure Secrets

Never commit secrets to version control
Use environment variables or secret managers
Rotate API keys regularly

3. Database Security

Use strong passwords
Enable SSL for database connections
Restrict network access

4. Rate Limiting

Configure rate limits in nginx:

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

location / {
    limit_req zone=api burst=20;
    proxy_pass http://api;
}

5. Firewall Rules

# Allow only HTTPS
ufw allow 443/tcp

# Allow SSH (if needed)
ufw allow 22/tcp

# Enable firewall
ufw enable

Scaling

Horizontal Scaling

# Kubernetes HPA
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: quantumlock-api-hpa
  namespace: quantumlock
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: quantumlock-api
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

Database Connection Pooling

# config.py
SQLALCHEMY_POOL_SIZE = 20
SQLALCHEMY_MAX_OVERFLOW = 10
SQLALCHEMY_POOL_PRE_PING = True

Troubleshooting

API Not Starting

Check logs:

docker logs quantumlock-api
kubectl logs -f deployment/quantumlock-api -n quantumlock

Common issues:

Database connection failed → Check DATABASE_URL
Secret key not set → Set SECRET_KEY env var
Port already in use → Change port mapping

Database Connection Issues

Test connection:

docker exec -it postgres psql -U quantumlock -d quantumlock

Performance Issues

Check metrics:

# CPU usage
docker stats

# Database queries
kubectl exec -it postgres -- psql -U quantumlock -c "SELECT * FROM pg_stat_activity;"

Next Steps

API Reference - REST API endpoints
SDK Reference - Client libraries
CLI Reference - Command-line tools
Getting Started - Quick start guide

Support

📧 Email: support@softquantus.com
💬 Discord: https://discord.gg/softquantus
📚 Documentation: https://docs.softquantus.com
🐛 Issues: https://github.com/softquantus/quantumlock/issues

Overview​

Docker Deployment​

Quick Start​

docker-compose.yml​

Environment Variables​

SSL/TLS Configuration​

Kubernetes Deployment​

Namespace​

Secrets​

PostgreSQL​

API Deployment​

Ingress​

Deploy​

Cloud Deployments​

AWS (ECS + RDS)​

Azure (Container Apps + PostgreSQL)​

GCP (Cloud Run + Cloud SQL)​

Monitoring​

Prometheus + Grafana​

Health Checks​

Logging​

Backup & Recovery​

Database Backup​

Restore​

Security Best Practices​

1. Use HTTPS Only​

2. Secure Secrets​

3. Database Security​

4. Rate Limiting​

5. Firewall Rules​

Scaling​

Horizontal Scaling​

Database Connection Pooling​

Troubleshooting​

API Not Starting​

Database Connection Issues​

Performance Issues​

Next Steps​

Support​