Your OMSS Compliant Streaming Backend Template 🚀

Production‐ready starter template for building OMSS‐compliant streaming backends. Includes server setup, provider system, linting, and an example provider.

Features ✅

🚀 Ready in 5 minutes – install, set TMDB key, run
📦 @omss/framework – official OMSS implementation
🔌 Auto‐discovery – drop provider files into providers/
🛡️ Type safety & formatting – Prettier + TypeScript
📊 Production‐ready – Redis cache, Docker support
🎭 Example provider – fully commented reference implementation
🔄 Hot reload – npm run dev for development

Quick Start ⏱️

# Clone & install
git clone https://github.com/omss-spec/template.git my-streaming-backend
cd my-streaming-backend
npm install
# Copy env template
cp .env.example .env
# !Add your TMDB API key!
# Run dev server (auto-reload)
npm run dev

✅ Server running at http://localhost:3000

Great! You can now add your providers!

📁 Structure

template/
├── src/
│ ├── server.ts # Main server entrypoint
│ ├── providers/ # Auto-discovered providers
│ │ └── example.ts # Reference provider
├── .env.example # Environment template
├── .prettierrc # Prettier config
├── tsconfig.json # TypeScript config
├── package.json # Dependencies + scripts

🛠️ Scripts

npm run dev # Dev server with hot reload (tsx watch)
npm run main # Run server (production mode)

🔌 Adding Providers

1. Create a provider (extends BaseProvider):

// src/providers/my-site.ts
import { BaseProvider } from "@omss/framework";
export class MySiteProvider extends BaseProvider {
 readonly id = "my-site";
 readonly name = "My Site";
 readonly BASE_URL = "https://my-site.com";
 readonly capabilities = { supportedContentTypes: ["movies", "tv"] };
 // Implement getMovieSources() & getTVSources()
}

2. Auto‐discovered – restart server or use npm run dev (watches for changes)

3. Register manually (in server.ts):

server.getRegistry().register(new MySiteProvider());

⚙️ Environment

Copy .env.example → .env and set:

# Required
TMDB_API_KEY=your_tmdb_api_key_here
# Optional
PORT=3000
HOST=localhost
NODE_ENV=development
PUBLIC_URL=http://localhost:3000
# Redis (for production)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

🐳 Docker Deployment

Quick Start with Docker

Option 1: Docker Compose (Recommended for Production)

Includes Redis cache for optimal performance

# 1. Create .env file
cp .env.example .env
# Edit .env and add your TMDB_API_KEY
# 2. Start services (backend + Redis)
docker-compose up -d
# 3. View logs
docker-compose logs -f omss-backend
# Server running at http://localhost:3000

Option 2: Standalone Docker (Memory Cache)

# 1. Build the image
docker build -t omss-backend:latest .
# 2. Run container
docker run -p 3000:3000 \
 -e TMDB_API_KEY=your_tmdb_api_key_here \
 -e CACHE_TYPE=memory \
 omss-backend:latest
# Server running at http://localhost:3000

Docker Configuration

Build Arguments

Customize the build with --build-arg:

docker build \
 --build-arg NODE_ENV=production \
 --build-arg PORT=8080 \
 --build-arg CACHE_TYPE=memory \
 -t omss-backend:latest .

Runtime Environment Variables

All .env variables can be overridden at runtime:

docker run -p 3000:3000 \
 -e TMDB_API_KEY=your_key \
 -e TMDB_CACHE_TTL=86400 \
 -e CACHE_TYPE=redis \
 -e REDIS_HOST=redis.example.com \
 -e REDIS_PORT=6379 \
 -e REDIS_PASSWORD=your_password \
 -e PORT=3000 \
 -e HOST=0.0.0.0 \
 -e PUBLIC_URL=https://api.yourdomain.com \
 omss-backend:latest

Docker Compose Services

The docker-compose.yml includes:

omss-backend: Your OMSS streaming backend
redis: Redis cache (persistent storage)

Customizing docker-compose.yml

# Change exposed port
ports:
 - "8080:3000" # Access on port 8080
# Add Redis password
redis:
 command: redis-server --requirepass yourpassword
# Then update backend environment
environment:
 - REDIS_PASSWORD=yourpassword

Production Deployment Tips

Use Redis cache for better performance:

environment:
 - CACHE_TYPE=redis
 - REDIS_HOST=redis

Set PUBLIC_URL if behind reverse proxy:

environment:
 - PUBLIC_URL=https://api.yourdomain.com

Persistent data is stored in Docker volume redis-data
Health checks: Access http://localhost:3000/ to verify

Troubleshooting Docker

Port already in use:

# Change port in docker-compose.yml
ports:
 - "3001:3000"

Providers not loading: Ensure your src/server.ts uses the correct path:

registry.discoverProviders(
 process.env.NODE_ENV === "production"
 ? "./dist/providers"
 : "./src/providers",
);

🔧 Development Workflow

# 1. Install
npm install
# 3. Add providers to src/providers/
# 2. Dev server (auto-reload + type checking)
npm run dev
# 4. Format code
npm run format
# 5. Build for prod
npm run build
npm run start

📚 Reference

OMSS Framework: @omss/framework on npm github
OMSS Spec: github.com/omss-spec/omss-spec
Example Provider: src/providers/example.ts – fully commented
Server Examples: src/server.ts – multiple configs

See src/providers/example.ts for a complete provider implementation with error handling, logging, proxying, and type safety.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

📄 License

⭐ Star this repo | [Click on 'Use this template' & customize] | OMSS Spec

Name		Name	Last commit message	Last commit date
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
compose.yml		compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Uh oh!

Latest commit

History

Folders and files

Repository files navigation