Skip to main content
Run the ČSFD API as a standalone REST service using Docker. Perfect for microservices, serverless deployments, or when you need a dedicated API server.

​
Using Pre-built Image

The easiest way to get started is using the official pre-built image from Docker Hub.
1

Pull the latest image

docker pull bartholomej/node-csfd-api
2

Run the container

docker run -p 3000:3000 bartholomej/node-csfd-api
3

Verify it's running

Navigate to http://localhost:3000/movie/535121 to test the API.
The official Docker image is available at bartholomej/node-csfd-api

​
Building Your Own Image

If you want to customize the image or build from source, you can build it yourself.

​
Dockerfile Overview

The Dockerfile uses a multi-stage build for optimal image size: 
# --- STAGE 1: Build & Prune ---
FROM node:24-alpine AS build

WORKDIR /usr/src/app

# Enable Corepack for Yarn 4
RUN corepack enable

# Copy dependency files first for layer caching
COPY package.json yarn.lock .yarnrc.yml ./
COPY .yarn/ .yarn/

# Install all dependencies (including devDependencies) needed for build
RUN yarn install --immutable

# Copy all source files
COPY . .

# Build the application (compiles to /dist)
RUN yarn build

# Install Yarn workspace-tools plugin and prune to strictly production dependencies
RUN yarn workspaces focus --all --production

# --- STAGE 2: Production (Ultra-lean) ---
FROM node:24-alpine AS production

WORKDIR /usr/src/app
ENV NODE_ENV=production

# Copy ONLY the built application
COPY --from=build /usr/src/app/dist ./dist

# Copy ONLY the production-ready node_modules
COPY --from=build /usr/src/app/node_modules ./node_modules

# Copy package.json (often required by Node.js for ESM/module resolution)
COPY package.json ./

EXPOSE 3000

# Start the application
CMD ["node", "dist/bin/server.mjs"]

​
Build Steps

# Clone the repository (if not already)
git clone https://github.com/bartholomej/node-csfd-api.git
cd node-csfd-api

# Build the Docker image
docker build -t node-csfd-api .

​
Port Mappings & Configuration

The Docker container exposes port 3000 by default. You can map it to any port on your host machine.

​
Port Mapping Examples

# Default mapping (3000 -> 3000)
docker run -p 3000:3000 bartholomej/node-csfd-api

# Custom host port (8080 -> 3000)
docker run -p 8080:3000 bartholomej/node-csfd-api

# Run in detached mode
docker run -d -p 3000:3000 bartholomej/node-csfd-api

# Run with a custom name
docker run -d --name csfd-api -p 3000:3000 bartholomej/node-csfd-api

​
Environment Variables

The container sets NODE_ENV=production by default. You can override environment variables if needed: 
docker run -p 3000:3000 \
  -e NODE_ENV=production \
  bartholomej/node-csfd-api
The Docker image uses Node.js 24 Alpine Linux for minimal size and optimal performance.

​
REST API Endpoints

Once the container is running, the following REST API endpoints are available:
EndpointDescriptionExample
/movie/:idGet movie details by ČSFD ID/movie/535121
/search/:querySearch for movies, series, users/search/tarantino
/creator/:idGet creator/actor info/creator/2120
/user-ratings/:usernameGet user ratings/user-ratings/912-bart
/user-reviews/:userIdGet user reviews/user-reviews/195357

​
Example Requests

# Get movie details
curl http://localhost:3000/movie/535121
Returns comprehensive movie information including ratings, cast, genres, and more.

​
Docker Compose

For more complex setups, you can use Docker Compose:
docker-compose.yml
version: '3.8'

services:
  csfd-api:
    image: bartholomej/node-csfd-api
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/movie/1"]
      interval: 30s
      timeout: 10s
      retries: 3
Run with: 
docker-compose up -d

​
Production Deployment

For production deployments, consider implementing:
  • Rate limiting (using nginx or a reverse proxy)
  • Caching layer (Redis, Memcached)
  • Load balancing for multiple containers
  • Monitoring and logging

​
Example with Nginx Reverse Proxy

server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_valid 200 1h;
    }
}

​
Troubleshooting

Check the logs to see what went wrong:
docker logs <container-id>
If port 3000 is already in use, map to a different port:
docker run -p 8080:3000 bartholomej/node-csfd-api
Ensure the container is running:
docker ps
And that you’re using the correct host port in your requests.
Make sure you have the latest version of Docker and sufficient disk space:
docker --version
df -h

​
Next Steps

TypeScript Types

Learn about the TypeScript type definitions

MCP Integration

Use ČSFD data with AI assistants

Build docs developers (and LLMs) love

Get started for freeTalk to us