Cutia Deployment & Usage Guide

A practical guide for deploying and running Cutia, a privacy-focused, open-source video editor that runs entirely in the browser.

Prerequisites

Before you begin, ensure you have the following installed:

• Bun (v1.0+): The primary package manager and runtime. Install from bun.sh.
• Git: For cloning the repository.
• Docker & Docker Compose: Required only for the full local setup with PostgreSQL and Redis services.
• OpenSSL: For generating authentication secrets (typically pre-installed on macOS/Linux; on Windows, use Git Bash or WSL).

Installation

Choose the setup path that matches your needs:

Minimal Setup (Frontend-Only, No Services)

This mode uses browser storage (IndexedDB) and is ideal for quick testing or basic editing without a backend.

git clone https://github.com/msgbyte/cutia.git
cd cutia/apps/web
cp .env.example .env.local
bun install
bun dev

Open http://localhost:3000 in your browser.

Full Setup (With Persistent Storage)

This mode enables project saving, user accounts, and other backend features using PostgreSQL and Redis.

# 1. Start the required services (PostgreSQL and Redis)
git clone https://github.com/msgbyte/cutia.git
cd cutia
docker-compose up -d

# 2. Configure the web application
cd apps/web
cp .env.example .env.local

Edit .env.local and set the required environment variables (see Configuration section).

# 3. Install dependencies and run database migrations
bun install
bun run db:migrate

# 4. Start the development server
bun dev

Open http://localhost:3000.

Configuration

The application is configured via environment variables in .env.local. Below are the required variables for the full setup:

For minimal (frontend-only) setup, you can set only:

• BETTER_AUTH_SECRET (any random string)
• BETTER_AUTH_URL (e.g., http://localhost:3000)

Other variables can be left empty or omitted, as the app will fall back to browser storage.

Build & Run

Development

cd apps/web
bun dev

The app will hot-reload at http://localhost:3000.

Production Build

cd apps/web
bun run build   # Creates optimized production build in .next
bun run start   # Starts the production server (default port 3000)

Note: The db:migrate script should be run after bun install and before starting the app in production if you're using a fresh database. The app also runs migrations automatically on startup, but pre-running them is recommended for reliability.

Deployment

Recommended: Vercel

Cutia is a Next.js application and deploys seamlessly on Vercel.

1. Click the Deploy with Vercel button in the README, or import the repository manually in the Vercel dashboard.
2. During setup, configure the environment variables listed in the Configuration section.
3. Provision add-ons for PostgreSQL and Redis:
   • In Vercel, add Vercel Postgres and Vercel KV (Redis) to your project.
   • Copy the connection strings from these add-ons into DATABASE_URL and UPSTASH_REDIS_REST_URL/UPSTASH_REDIS_REST_TOKEN.
4. Deploy. Vercel will automatically detect the Next.js app and use the Bun runtime (ensure "Node.js Version" is set to bun in project settings if needed).

Other Platforms (Railway, Render, DigitalOcean, etc.)

Any platform that supports Node.js/Bun and can run PostgreSQL/Redis instances will work.

1. Build the app locally or on the platform:

   bun run build
   

2. Upload the .next folder and package.json/bun.lockb to your host.
3. Set up a PostgreSQL database and Redis instance separately.
4. Configure all environment variables with the produced connection strings.
5. Start the app with bun run start (ensure the host uses Bun as the runtime).

Important: The BETTER_AUTH_URL must be set to your production domain (e.g., https://your-app.vercel.app).

Troubleshooting

Common Issues