Quickstart: Run CinePro Core locally

Get a CinePro Core streaming backend running on your machine in 5-10 minutes using Docker or a local Node.js setup with your TMDB API key.

Prerequisites

Before you start, you will need:

• A TMDB API key — Get one for free at themoviedb.org

Docker (recommended)

1. Install Docker

   Make sure you have Docker installed and running. You can download it from docker.com.

2. Run CinePro Core with one command

   docker run --name cinepro-core -p 3000:3000 -e TMDB_API_KEY=your_tmdb_api_key_here ghcr.io/cinepro-org/core:latest
   

   This command pulls the latest CinePro Core image, starts it in a container, and exposes it on port 3000. Make sure to replace your_tmdb_api_key_here with your actual TMDB API key.

   You can add more environment variables as needed (e.g. HOST, PORT, CACHE_TYPE, etc.) — just append -e VAR_NAME=value for each one.

Windows (development)

1. Install Node.js

   Install Node.js v20 or higher.

   Using winget (recommended)

   winget install OpenJS.NodeJS.LTS
   

   Manual installer

   Download and run the LTS installer from nodejs.org.

   Verify your installation:

   node -v   # should print v20.x.x or higher
   npm -v
   
2. Clone the repository

   git clone https://github.com/cinepro-org/core.git
   cd core
   
3. Install dependencies

   npm install
   
4. Configure environment variables

   Copy the example environment file and fill in your values:

   copy .env.example .env
   

   Open .env in your editor and set at minimum:

   # Required
   TMDB_API_KEY=your_tmdb_api_key_here
   
   # Server
   PORT=3000
   HOST=localhost
   NODE_ENV=development
   
   # Cache (use 'memory' for local dev)
   CACHE_TYPE=memory
   

   CACHE_TYPE=memory is fine for development. Switch to redis for production deployments.

5. Start the dev server

   npm run dev
   

   CinePro Core will start with hot reload at http://localhost:3000.

Linux

1. Install Node.js

   Install Node.js v20 or higher.

   Using nvm (recommended)

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
   source ~/.bashrc
   nvm install 20
   nvm use 20
   

   Using apt (Ubuntu/Debian)

   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   sudo apt-get install -y nodejs
   

   Verify your installation:

   node -v   # should print v20.x.x or higher
   npm -v
   
2. Clone the repository

   git clone https://github.com/cinepro-org/core.git
   cd core
   
3. Install dependencies

   npm install
   
4. Configure environment variables

   cp .env.example .env
   

   Edit .env and set at minimum:

   # Required
   TMDB_API_KEY=your_tmdb_api_key_here
   
   # Server
   PORT=3000
   HOST=localhost
   NODE_ENV=development
   
   # Cache
   CACHE_TYPE=memory
   
5. Start the dev server

   npm run dev
   

   CinePro Core will start with hot reload at http://localhost:3000.

macOS

1. Install Node.js

   Install Node.js v20 or higher.

   Using Homebrew (recommended)

   brew install node@20
   

   Using nvm

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
   source ~/.zshrc
   nvm install 20
   nvm use 20
   

   Verify your installation:

   node -v   # should print v20.x.x or higher
   npm -v
   
2. Clone the repository

   git clone https://github.com/cinepro-org/core.git
   cd core
   
3. Install dependencies

   npm install
   
4. Configure environment variables

   cp .env.example .env
   

   Edit .env and set at minimum:

   # Required
   TMDB_API_KEY=your_tmdb_api_key_here
   
   # Server
   PORT=3000
   HOST=localhost
   NODE_ENV=development
   
   # Cache
   CACHE_TYPE=memory
   
5. Start the dev server

   npm run dev
   

   CinePro Core will start with hot reload at http://localhost:3000.

Docker (compose)

Docker Compose is the recommended production deployment method. It includes a Redis instance automatically.

This is overkill if you just want to run a local dev server, but it’s a great way to get a production-like environment up and running quickly.

1. Install Docker

   Download and install Docker Desktop (includes Compose).

   Verify:

   docker -v
   docker compose version
   
2. Clone the repository

   git clone https://github.com/cinepro-org/core.git
   cd core
   
3. Configure environment variables

   cp .env.example .env
   

   The only variable required by compose.yml is TMDB_API_KEY — Redis is configured automatically:

   TMDB_API_KEY=your_tmdb_api_key_here
   

   The Compose file sets CACHE_TYPE=redis and wires REDIS_HOST=redis automatically. You don’t need to change those values.

4. Start services

   docker compose up -d
   

   This builds the cinepro-core image and starts it alongside a Redis 7 Alpine container on a shared bridge network. The server is exposed on port 3000.

5. View logs

   docker compose logs -f cinepro-core
   

---

Production build (without Docker)

If you prefer running without Docker in a production environment:

# 1. Build the TypeScript source
npm run build

# 2. Set production env vars
NODE_ENV=production

# 3. Start the compiled server
npm start

Set NODE_ENV=production to silence debug logging. For persistence across restarts consider a process manager such as PM2 (pm2 start dist/server.js).

---

Available scripts

Command	Description
npm run dev	Development server with hot reload
npm run build	Compile TypeScript to dist/
npm start	Start production server (requires build first)
npm run format	Format code with Prettier

---

Explore the API

Your server is running — dive into the OMSS-compliant endpoint reference to start fetching movie and TV show sources.

Configure providers

Learn how to enable, disable, or add new streaming source providers to your CinePro Core instance.

Open the CinePro UI

Use the CinePro UI (public beta) to browse and stream from your instance in the browser. On startup, the server prints a ready-to-use link of the form https://ui.cinepro.cc/?omssurl=<your-instance-url> derived from your PUBLIC_URL.