Deployment

Deployment

MuxCore scales from a single machine to a globally distributed cluster without changing the architecture. Start simple — one Docker container, like Sonarr. Grow to multiple machines when you need to.

---

Phase 1: Single Machine

The simplest setup — one machine, one binary, all modules compiled in.

docker compose up

What You Get

┌──────────────────────────┐
│      Docker Host          │
│                           │
│  ┌──────────────────────┐ │
│  │  MuxCore              │ │
│  │  (core + all modules) │ │
│  │                       │ │
│  │  HTTP API  → :8080   │ │
│  │  gRPC Mesh → :9090   │ │
│  │  Admin UI             │ │
│  └──────────────────────┘ │
└──────────────────────────┘

• Single binary with embedded modules
• In-memory event bus (zero external dependencies)
• Local filesystem storage
• No database needed for single-node
• Just as easy as installing Sonarr

Build Variants

# Default preset — admin UI, REST API, scheduler
go build -tags default ./cmd/muxcored

# Bare loom — zero modules, just the platform
go build ./cmd/muxcored

# Custom preset — create your own imports file
go build -tags mypreset ./cmd/muxcored

Configuration

All settings go in muxcore.json or environment variables. See Getting Started for the full config reference.

---

Phase 2: Multiple Machines

Add worker nodes for distributed transcoding, storage, and failover.

┌─────────────────────┐
│   MuxCore Node 1    │  (primary — API, UI, event bus)
│   - Core services   │
│   - Database module │
│   - Cache module    │
└─────────┬───────────┘
          │
    ┌─────┴─────────────┐
    │                   │
┌───▼─────────┐  ┌──────▼────────┐
│ Worker 1    │  │ Worker 2      │
│ - Transcoder│  │ - Transcoder  │
│ - GPU: RTX  │  │ - GPU: GTX    │
│ - Local SSD  │  │ - Local SSD   │
└─────────────┘  └───────────────┘

New Capabilities

• Distributed transcoding — tasks go to the least-loaded GPU
• Worker failover — if worker 1 dies, tasks move to worker 2
• Shared task queue — backed by cache module (Redis/Valkey)
• Shared metadata — backed by database module (Postgres/SQLite)
• Module mobility — move a module to a different machine

Database and Cache Are Modules

PostgreSQL and Redis are not built into core. They're modules you install:

# docker-compose.yml
services:
  muxcore:
    image: muxcore-media/core:latest
    environment:
      - MUXCORE_DATABASE_DRIVER=postgres
      - MUXCORE_DATABASE_URL=postgres://...
      - MUXCORE_CACHE_DRIVER=redis
      - MUXCORE_CACHE_URL=redis://...

  postgres:
    image: postgres:16

  redis:
    image: redis:7

Pick the database and cache that fit your setup — SQLite for single-node, Postgres for multi-node, Redis or Valkey for caching.

---

Phase 3: Kubernetes

Full cloud-native orchestration:

┌───────────────────────────────────────┐
│         Kubernetes Cluster             │
│                                       │
│  ┌──────────┐  ┌──────────┐          │
│  │ MuxCore  │  │ MuxCore  │  (HA)    │
│  │ Pod 1    │  │ Pod 2    │          │
│  └──────────┘  └──────────┘          │
│                                       │
│  ┌──────────────────────────────┐     │
│  │     GPU Worker Pool          │     │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ │     │
│  │  │GPU 1 │ │GPU 2 │ │GPU 3 │ │     │
│  │  └──────┘ └──────┘ └──────┘ │     │
│  └──────────────────────────────┘     │
│                                       │
│  ┌──────────────────────────────┐     │
│  │     Storage                   │     │
│  │  ┌─────────┐ ┌──────────┐    │     │
│  │  │ Rook/   │ │ MinIO    │    │     │
│  │  │ Ceph    │ │ (S3)     │    │     │
│  │  └─────────┘ └──────────┘    │     │
│  └──────────────────────────────┘     │
└───────────────────────────────────────┘

New Capabilities

• Auto-scaling worker pools
• Multi-node database (HA Postgres)
• Redis/Valkey cluster
• Helm chart deployment
• GitOps (Flux/ArgoCD)
• Multi-tenant support

---

Clustering: Auto-Join

When you add a new node, it can automatically join the existing cluster:

On the New Node

Set seed nodes and join token in muxcore.json:

{
  "grpc": {
    "addr": ":9090",
    "seed_nodes": ["primary-node:9090"],
    "join_token": "my-secret-cluster-token"
  }
}

Or with environment variables:

export MUXCORE_GRPC_SEED_NODES="primary-node:9090,backup-node:9090"
export MUXCORE_CLUSTER_JOIN_TOKEN="my-secret-cluster-token"

What Happens

1. New node starts → contacts seed nodes
2. Presents join token → seed node validates it
3. Receives cluster member list + leader ID
4. Registers with the cluster
5. Other nodes discover it via cluster events

---

Module Deployment (Multi-Machine)

In Phase 2+, modules can run as separate containers:

# docker-compose.yml
services:
  muxcore:
    image: muxcore-media/core:latest

  downloader-qbittorrent:
    image: muxcore-media/downloader-qbittorrent:latest
    environment:
      - MUXCORE_ADDR=muxcore:8080
      - MODULE_TOKEN=***

  transcoder-ffmpeg:
    image: muxcore-media/transcoder-ffmpeg:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

---

Deployment Environments

Environment	Phase 1	Phase 2	Phase 3
Home lab	Docker Compose	Cluster	K3s
Seedbox	Single binary	Cluster	K8s
Enterprise	—	Cluster	K8s/Nomad
Media provider	—	—	Full K8s

---

Observability

Phase	What You Get
Phase 1	Structured logging, /health endpoint, trace ID propagation
Phase 2	Prometheus metrics, Grafana dashboards, audit logs
Phase 3	Distributed tracing, centralized logging (Loki/ELK)

---

Next Steps

• Getting Started — single-machine setup
• Security — TLS, mTLS, and join token configuration
• Roadmap — what's coming next