arrrrniii/mediaos repository overview

⁠MediaOS

Self-hosted open-source media infrastructure platform.

Upload, process, and serve images, videos, and files at scale. Think self-hosted Cloudinary / Imgix / Mux — with a built-in admin dashboard.

⁠What is MediaOS?

MediaOS is a complete media backend you can self-host. It replaces the patchwork of S3 + image CDN + video transcoder + dashboard that most teams build from scratch.

One docker compose up gives you:

• Image upload with automatic WebP conversion
• Video upload with H.264 transcoding + thumbnail extraction
• On-the-fly image resizing (200+ resize URLs per image)
• Multi-tenant projects with scoped API keys
• Signed URLs for private file access
• Webhooks with HMAC signatures
• Per-project usage analytics
• Full admin dashboard (Next.js)
• TypeScript SDK

⁠Quick Start

⁠One-line install

curl -fsSL https://raw.githubusercontent.com/arrrrniii/MediaOs/main/install.sh | bash

Pulls images, generates secure secrets, and starts all services. Done in under a minute.

⁠Manual setup

curl -O https://raw.githubusercontent.com/arrrrniii/MediaOs/main/docker-compose.hub.yml
curl -O https://raw.githubusercontent.com/arrrrniii/MediaOs/main/.env.example
cp .env.example .env
# Edit .env with your MASTER_KEY (generate with: node -e "console.log('mv_master_' + require('crypto').randomBytes(24).toString('hex'))")
docker compose -f docker-compose.hub.yml up -d

⁠Open the dashboard

• Dashboard: http://localhost:3001⁠ (setup wizard on first launch)
• API: http://localhost:3000⁠

⁠API-only mode (no dashboard)

# In .env, set:
COMPOSE_PROFILES=

Run docker compose up -d — only the worker API and infrastructure start. Manage everything via API.

⁠Images

⁠Supported Architectures

Both images support linux/amd64 and linux/arm64 (Apple Silicon, AWS Graviton).

# Pull the worker
docker pull arrrrniii/mediaos:worker

# Pull the dashboard
docker pull arrrrniii/mediaos:dashboard

⁠Services

MediaOS runs as a 6-service stack:

Only the Worker API and Dashboard expose ports. All infrastructure communicates over Docker's internal network.

⁠Features

⁠File Processing

• Images — Auto WebP conversion, configurable quality, max dimension enforcement
• Videos — H.264 MP4 transcoding, auto thumbnail, async processing with webhooks
• Audio — Duration extraction, stored as-is
• Documents — Any file type with proper MIME handling

⁠Image Resizing

Every image gets instant resize URLs powered by imgproxy:

/f/{key}                         → Original
/img/fit/200/200/f/{key}         → Fit within 200x200
/img/fill/500/500/f/{key}        → Fill 500x500 (crop)
/img/auto/800/0/f/{key}          → Smart resize, 800px wide

⁠Dashboard

• File browser with image previews and preview modal
• Single file download and bulk ZIP export for backups
• API key management, webhook management, usage analytics
• Auto-update notification when a new release is available
• Dark/light theme, responsive design

⁠Multi-Tenant

• Accounts with multiple projects
• Projects with isolated storage, keys, and settings
• API Keys with scoped permissions (upload, read, delete, admin)
• Rate limiting per key via Redis

⁠Security

• SHA-256 hashed API keys (prefix lookup, constant-time compare)
• HMAC-SHA256 signed URLs and webhook signatures
• bcrypt password hashing
• Parameterized SQL (no injection)
• Helmet security headers

⁠Deployment

• One-line installer with smart port detection
• Optional dashboard (API-only mode via COMPOSE_PROFILES=)
• Reverse proxy configs for Nginx, Caddy, and Traefik
• One-line updater: curl -fsSL .../update.sh | bash
• Zero-downtime updates — data lives in Docker volumes

⁠Configuration

Key environment variables (see .env.example for full list):

⁠SDK

npm install @mediaos/sdk

import { MediaOS } from '@mediaos/sdk';

const media = new MediaOS({
  url: 'https://cdn.yoursite.com',
  apiKey: 'mv_live_...',
});

// Upload
const file = await media.upload(buffer, { name: 'hero.jpg', folder: 'images' });

// Resize URL (no API call)
const thumb = media.url(file.storage_key, { width: 300, height: 300, fit: 'fill' });

// List files
const files = await media.files.list({ type: 'image', limit: 20 });

⁠API Example

# Upload an image
curl -X POST http://localhost:3000/api/v1/upload \
  -H "X-API-Key: mv_live_..." \
  -F "[email protected]"

# Response includes optimized WebP + resize URLs
{
  "filename": "photo-a8x3k2.webp",
  "url": "http://localhost:3000/f/proj-id/photo-a8x3k2.webp",
  "urls": {
    "thumb": "http://localhost:3000/img/fit/200/200/f/proj-id/photo-a8x3k2.webp",
    "sm": "http://localhost:3000/img/fit/400/0/f/proj-id/photo-a8x3k2.webp",
    "md": "http://localhost:3000/img/fit/800/0/f/proj-id/photo-a8x3k2.webp",
    "lg": "http://localhost:3000/img/fit/1200/0/f/proj-id/photo-a8x3k2.webp"
  },
  "type": "image",
  "size": 45200,
  "processing_ms": 124
}

⁠Updating

curl -fsSL https://raw.githubusercontent.com/arrrrniii/MediaOs/main/update.sh | bash

Or manually: docker compose pull && docker compose up -d. Your data is safe — everything lives in Docker volumes.

⁠Roadmap

MediaOS is evolving into a complete open-source media platform:

⁠Links

• GitHub: github.com/arrrrniii/MediaOs⁠
• Documentation: GitHub README⁠
• Issues: Report bugs⁠
• Contributing: CONTRIBUTING.md⁠
• Roadmap: ROADMAP.md⁠

MIT License — Free to use for personal and commercial projects.

Built by ARN⁠