Skip to main content
This guide will help you set up a local development environment for OpenCut.

​
Prerequisites

Before you begin, ensure you have the following installed:
Docker is optional but recommended for running the local database and Redis services. If you only want to work on frontend features, you can skip the Docker setup.

​
Installation

1

Fork and clone the repository

Fork the OpenCut repository to your GitHub account, then clone it locally:
2

Copy environment variables

Copy the example environment file to create your local configuration:
3

Configure environment variables

Open apps/web/.env.local and configure the required variables:

​
Generate authentication secret

Generate a secure BETTER_AUTH_SECRET using one of these methods:
Or use an online generator: generate-secret.vercel.app/32
The .env.example file has sensible defaults that match the Docker Compose configuration. For basic development, you only need to set BETTER_AUTH_SECRET.
4

Start Docker services

Start the PostgreSQL database and Redis services:
This starts:
  • PostgreSQL on port 5432
  • Redis on port 6379
  • Serverless Redis HTTP on port 8079 (Upstash-compatible REST API)
5

Install dependencies

Install all project dependencies using your preferred package manager:
If you see an error like Unsupported URL Type "workspace:*" when using npm, upgrade to npm v9 or later, or use Bun or pnpm instead.
6

Run database migrations

Apply database migrations to set up the schema:
7

Start the development server

Start the Next.js development server from the project root:
The application will be available at http://localhost:3000.

​
Optional services

The following environment variables are optional and can be configured for additional features:

​
Blog integration

Required for blog content powered by Marble CMS.

​
Audio library

Required for audio library integration with Freesound.

​
Auto-captions (transcription)

Required for automatic caption generation using Cloudflare R2 and Modal.

​
Self-hosting with Docker

To run a complete production build in Docker:
The application will be available at http://localhost:3100.
The Docker production build includes all services: database, Redis, and the Next.js application.

​
Available scripts

From the project root:
  • bun dev:web - Start the web development server
  • bun build:web - Build the web application for production
  • bun test - Run all tests
  • bun lint:web - Check for linting issues
  • bun lint:web:fix - Fix linting issues automatically
  • bun format:web - Format code with Biome
From apps/web/:
  • bun run dev - Start development server with Turbopack
  • bun run build - Build for production
  • bun run lint - Check linting with Biome
  • bun run lint:fix - Fix linting issues
  • bun run format - Format code
  • bun run db:generate - Generate database migrations
  • bun run db:migrate - Run database migrations
  • bun run db:push:local - Push schema changes to local database
  • bun run db:push:prod - Push schema changes to production

​
Troubleshooting

​
Docker services not starting

If Docker services fail to start, check that ports 5432, 6379, and 8079 are not already in use:

​
Database connection errors

Ensure the DATABASE_URL in .env.local matches the Docker Compose configuration:

​
Package manager issues

If you encounter workspace protocol errors with npm, either:
  1. Upgrade to npm v9 or later: npm install -g npm@latest
  2. Use Bun or pnpm instead

​
Next steps

Architecture

Learn about OpenCut’s system architecture

Contributing

Start contributing to the project