Dockerizing a Remotion app
We recommend the following structure for your Dockerfile. Read below about the individual steps and whether you need to adjust them.
DockerfileFROM node:22-bookworm-slim # Install Chrome dependencies RUN apt-get update RUN apt install -y \ libnss3 \ libdbus-1-3 \ libatk1.0-0 \ libgbm-dev \ libasound2 \ libxrandr2 \ libxkbcommon-dev \ libxfixes3 \ libxcomposite1 \ libxdamage1 \ libatk-bridge2.0-0 \ libpango-1.0-0 \ libcairo2 \ libcups2 # Copy the package files from your project to the Docker image. Adjust if needed. COPY package.json package*.json yarn.lock* pnpm-lock.yaml* bun.lockb* bun.lock* tsconfig.json* ./ # Install the right package manager and dependencies - see below for Yarn/PNPM RUN npm i # Install Chrome RUN npx remotion browser ensure # Copy your source code and config file COPY src ./src COPY remotion.config.* ./ # If you have a public folder: COPY public ./public # Run your application COPY render.mjs render.mjs CMD ["node", "render.mjs"]
Click here to see an example for a render.mjs script you can use.
Line-by-line
1 Specify the base image for the Dockerfile. In this case, we use Debian.
FROM node:22-bookworm-slim2 Update the package lists on the Debian system and install the needed shared libraries for Chrome Headless Shell.
RUN apt-get update
RUN apt install -y \
libnss3 \
libdbus-1-3 \
libatk1.0-0 \
libgbm-dev \
libasound2 \
libxrandr2 \
libxkbcommon-dev \
libxfixes3 \
libxcomposite1 \
libxdamage1 \
libatk-bridge2.0-0 \
libpango-1.0-0 \
libcairo2 \
libcups23 Copy the package files from your project. If some files do not exist, remove them. The COPY syntax allows multiple files, but at least one file must exist.
COPY package.json package*.json yarn.lock* pnpm-lock.yaml* bun.lockb* bun.lock* tsconfig.json* ./The Dockerfile copies the source code and the config file after installing dependencies and Chrome. That way, Docker reuses the cached dependency and Chrome layers when only your source code changes.
4 Install the right package manager and dependencies.
-
If you use NPM, put the following in your Dockerfile:
RUN npm i -
If you use Yarn or PNPM, add the
packageManagerfield to yourpackage.json(example:"packageManager": "[email protected]") and remove thenpmline above. Then put following in your Dockerfile:If you use PNPMRUN corepack enable RUN pnpm iIf you use YarnRUN corepack enable RUN yarn
5 Install Chrome Headless Shell.
RUN npx remotion browser ensure6 Copy the files from your project. If you have additional source files, add them here. This step assumes that src, a remotion.config.ts file and public exist in your project. Adjust it to your needs.
COPY src ./src
COPY remotion.config.* ./
COPY public ./publicCopy the config file together with src, because it may import files from src. Every remotion CLI command, including browser ensure, loads the config file.
7 Run your code. It can be a CLI command or a Node.JS app.
COPY render.mjs render.mjs
CMD ["node", "render.mjs"]Example render script
Assuming you want to render the composition MyComp:
render.mjsimport {bundle } from '@remotion/bundler'; import {renderMedia ,selectComposition } from '@remotion/renderer'; import {createRequire } from 'node:module'; constrequire =createRequire (import.meta .url ); constbundled = awaitbundle ({entryPoint :require .resolve ('./src/index.ts'), // If you have a webpack override in remotion.config.ts, pass it here as well.webpackOverride : (config ) =>config , }); constinputProps = {}; constcomposition = awaitselectComposition ({serveUrl :bundled ,id : 'MyComp',inputProps , });console .log ('Starting to render composition'); awaitrenderMedia ({codec : 'h264',composition ,serveUrl :bundled ,outputLocation : `out/${composition .id }.mp4`,chromiumOptions : {enableMultiProcessOnLinux : true, },inputProps , });console .log (`Rendered composition ${composition .id }.`);
From v4.0.137, enableMultiProcessOnLinux is enabled by default. On versions v4.0.42 to v4.0.136, set it explicitly for this Docker image as shown above.
Bundling ahead of time
The example script above calls bundle() every time the container starts.
For a long-running render server, create the bundle while building the image instead. Add this line after copying src and public:
RUN npx remotion bundle --out-dir=buildThen pass the path of the build folder as serveUrl to selectComposition() and renderMedia() instead of calling bundle().
Building the Docker image
Run
docker build -t remotion-app .to build a Docker image called remotion-app.
Use the following command to run the image:
docker run remotion-appGiving access to the CPUs
By default, Docker containers are not allowed to use all CPUs. Consider:
- Changing the resource settings in Docker Desktop settings
- Using the
--cpusand--cpuset-cpusflags with thedocker runcommand. Example:--cpus=16 --cpuset-cpus=0-15
Fonts
Chrome Headless Shell uses the fonts installed on the system. In the Dockerfile above, libpango-1.0-0 and libcairo2 install a basic font as a dependency.
If you change the list of packages or use a different base image, make sure at least one font is installed, for example by adding fonts-dejavu-core to the apt install list.
If no font is installed, text renders invisibly without an error.
Emojis
No emojis are installed by default. If you want to use emojis, install an emoji font:
RUN apt-get install fonts-noto-color-emojiJapanese, Chinese, Korean, etc.
Those fonts may have limited Character support enabled by default. If you need full support, install the following fonts:
RUN apt-get install fonts-noto-cjkWhy are the packages not pinned?
In Debian (and also Alpine), old packages are removed from the repositories once new versions are released. This means that pinning the versions will actually cause the Dockerfiles to break in the future. We choose Debian as the distribution because the packages get well tested before they get released into the repository.
Notes for older versions
-
If you are on a lower version than
v4.0.0, addffmpegto the list of packages to install:RUN apt-get install -y nodejs ffmpeg npm chromium -
If you are on Remotion
v3.3.80or lower, tell Remotion where Chrome is installed:ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
Recommendation: Don't use Alpine Linux
Alpine Linux is a lightweight distribution often used in Docker. There are two known issues with it when used in conjunction with Remotion:
- The launch of the Rust parts of Remotion may be very slow (>10sec slowdown per render)
- If a new version of Chrome gets released in the registry, you might be unable to downgrade because old versions are not kept and breaking changes can not be ruled out.
Changelog
November 6th, 2024: Use node:22-bookworm-slim over node:20-bookworm to update to LTS and get a much smaller image.
October 11th, 2023: Used the node:20-bookworm, which is faster to deploy and also Debian.
September 25th, 2023: Recommend setting enableMultiProcessOnLinux.
May 30th, 2023: Update document for Remotion 4.0.
April 15th, 2023: Unpinning the versions in Debian since it would cause breakage.
April 3rd, 2023: Changed the Alpine Docker image to a Debian one, since the versions of Alpine packages cannot be pinned. This makes the Debian one less likely to break.