Environment variables

Configure CinePro Core using environment variables. All configuration is done via a .env file in the project root.

Copy .env.example to .env before starting the server. CinePro Core will not start without a valid TMDB_API_KEY.

Required vs optional

Required

• TMDB_API_KEY — the server will crash on startup without it

Optional

• PORT, HOST, PUBLIC_URL, NODE_ENV — sensible defaults are built in - CACHE_TYPE, REDIS_* — only needed for Redis-backed caching in production

---

Server configuration

PORT · number · default: "3000"

The port CinePro Core listens on.

.env (development)

PORT=3000

.env (production — custom port)

PORT=8080

HOST · string · default: "localhost"

The hostname or IP address the server binds to.

Use localhost during development to keep the API private to your machine. Set to 0.0.0.0 in production or Docker deployments to accept connections from the LAN or internet.

.env (development)

HOST=localhost

.env (production / Docker)

HOST=0.0.0.0

PUBLIC_URL · string

The publicly accessible base URL of your CinePro Core instance. Used by the OMSS framework when generating absolute links in API responses (for example, stream URLs returned to clients).

Leave it unset locally — the framework will fall back to http://<HOST>:<PORT>.

.env (production)

PUBLIC_URL=https://api.example.com

Always include the protocol (https://) and no trailing slash. Incorrect values here will cause broken stream URLs in API responses.

NODE_ENV · string · default: "development"

Controls the runtime mode.

Value	Behavior
development	Verbose logging, detailed error messages, hot reload with npm run dev
production	Clean console output, minimal error exposure, optimised for npm start

.env (development)

NODE_ENV=development

.env (production)

NODE_ENV=production

TMDB configuration

TMDB_API_KEY · string · required

Your TMDB (The Movie Database) API key. CinePro Core uses this for all metadata lookups — movie/show titles, posters, IDs, and more. The server will fail to start if this is missing or invalid.

1. Create a TMDB account

   Go to themoviedb.org and sign up for a free account.
2. Request an API key

   Navigate to Settings → API and request a key. Choose the Developer option.
3. Add it to your .env

   bash .env TMDB_API_KEY=your_tmdb_api_key_here

TMDB API keys are free for non-commercial use. Keep your key private — do not commit .env to source control.

TMDB_CACHE_TTL · number · default: "86400"

How long (in seconds) TMDB metadata responses are cached. The default is 24 hours (86400).

Lowering this value keeps metadata fresher but increases TMDB API calls. Raising it reduces API usage at the cost of occasionally stale data.

.env

TMDB_CACHE_TTL=86400   # 24 hours (recommended)

---

Cache configuration

CACHE_TYPE · string · default: "memory"

Selects the caching backend. Accepted values are memory and redis.

Value	When to use
memory	Development or single-instance deployments with no persistence requirement
redis	Production deployments, especially where cache should survive restarts or be shared across instances

.env (development)

CACHE_TYPE=memory

.env (production)

CACHE_TYPE=redis

When CACHE_TYPE=redis, the REDIS_HOST, REDIS_PORT, and (optionally) REDIS_PASSWORD variables must also be set.

---

Redis configuration

These variables are only required when CACHE_TYPE=redis. If you are using memory cache you can leave them unset.

REDIS_HOST · string · default: "localhost"

Hostname or IP of your Redis instance.

.env (local Redis)

REDIS_HOST=localhost

.env (remote Redis / managed service)

REDIS_HOST=redis.example.com

REDIS_PORT · number · default: "6379"

Port your Redis instance listens on. The Redis default is 6379.

.env

REDIS_PORT=6379

REDIS_PASSWORD · string

Password for Redis authentication. Leave empty if your Redis instance has no password (e.g. a local dev instance).

.env (no password)

REDIS_PASSWORD=

.env (with password)

REDIS_PASSWORD=supersecretpassword

Never commit a Redis password to source control. Use a secrets manager or CI/CD environment injection in production.

Full .env reference

Development

A minimal .env for local development — memory cache, localhost binding, verbose logging.

.env

# Server
PORT=3000
HOST=localhost
NODE_ENV=development

# TMDB
TMDB_API_KEY=your_tmdb_api_key_here
TMDB_CACHE_TTL=86400

# Cache
CACHE_TYPE=memory

Production (with Redis)

A complete production .env with Redis caching and a public URL.

.env

# Server
PORT=8080
HOST=0.0.0.0
NODE_ENV=production
PUBLIC_URL=https://api.example.com

# TMDB
TMDB_API_KEY=your_tmdb_api_key_here
TMDB_CACHE_TTL=86400

# Cache
CACHE_TYPE=redis

# Redis
REDIS_HOST=redis.example.com
REDIS_PORT=6379
REDIS_PASSWORD=supersecretpassword

Docker Compose (with built-in Redis)

When using compose.yml, the Redis host is the Docker service name (redis) rather than localhost.

.env

# Server
PORT=3000
HOST=0.0.0.0
NODE_ENV=production
PUBLIC_URL=http://localhost:3000

# TMDB
TMDB_API_KEY=your_tmdb_api_key_here
TMDB_CACHE_TTL=86400

# Cache
CACHE_TYPE=redis

# Redis (Docker service name)
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=

When running via Docker Compose, REDIS_HOST should match the service name defined in compose.yml — not localhost.