Deployment & Installation Guide

Pluvira is distributed as a unified, production-ready container image containing the complete backend engine, database managers, and WebUI presentation layer.

---

1. Quickstart with Docker

Run the container directly with RAM disk acceleration enabled:

docker run -d \
  --name pluvira \
  --restart unless-stopped \
  -p 8585:8585 \
  --tmpfs /dev/shm:rw,size=256m \
  -v pluvira_data:/app/data \
  pluvira/app:latest

Once started, access the WebUI dashboard in your browser:

http://<host-ip>:8585

---

2. Docker Compose Configuration (Recommended)

Create a docker-compose.yml file in your preferred deployment directory:

services:
  pluvira:
    image: pluvira/app:latest
    container_name: pluvira
    restart: unless-stopped
    ports:
      - "8585:8585"
    tmpfs:
      - /dev/shm:rw,size=256m
    volumes:
      - ./data:/app/data
    environment:
      - APP_ENV=production
      - DEBUG=false
      - PLUVIRA_LICENSE_KEY=

Start the service in detached mode:

docker compose up -d

---

3. Storage & Performance Optimization

RAM Disk Mount (tmpfs)

To eliminate write amplification and protect solid-state drives (SSD/NVMe) from repeated micro-writes during EPG and feed updates, always allocate volatile memory to /dev/shm:

• Recommended size: 256MB to 512MB (--tmpfs /dev/shm:rw,size=256m).
• Function: All raw decompression, temporary databases, and dynamic streaming cache reside strictly in RAM.

Persistent Volume (/app/data)

The /app/data mount stores persistent application artifacts across container restarts:

• config.yaml: Core system preferences, source definitions, and user rewrite rules.
• pluvira_main.db: Relational channel definitions, source configurations, and curated playlists.

---

4. Networking & Firewall Configuration

Port	Protocol	Purpose	Access Scope
8585	TCP	WebUI Dashboard & REST API (/api/v1)	LAN / Reverse Proxy
3478	UDP/TCP	WebRTC NAT Traversal (STUN/TURN)	Outbound WAN

Zero-PII Authentication Service (Logto IAM)

When deploying the SaaS customer portal alongside the API, an integrated Logto container handles passwordless WebAuthn (Passkeys) and OAuth2 authentication, communicating with FastAPI via standard OIDC token verification.

Reverse Proxy & SSL Termination

When placing Pluvira behind an external reverse proxy (such as Nginx, Caddy, or Traefik), proxy traffic to container port 8585 (e.g. http://127.0.0.1:8585) and ensure standard forwarding headers are passed:

• X-Forwarded-For
• X-Forwarded-Proto
• WebSocket connection upgrade headers (Upgrade: $http_upgrade, Connection: "upgrade") for live dashboard events and remote signaling.