Comece pelo repositório certo
O repositório que aparece primeiro numa busca, OpenCut-app/OpenCut, está sendo
reescrito do zero. O app de desktop dele, nas palavras do próprio README, é hoje
“apenas uma janela que abre”. Se você seguir por ali, não vai conseguir editar nada.
A versão que funciona — e que roda no site oficial — é opencut-app/opencut-classic.
É essa que este guia instala.
Preparando o terreno
Duas ferramentas que o projeto exige e que provavelmente não estão na sua máquina.
Instale o Bun
O projeto usa Bun no lugar do npm. O instalador já adiciona o comando ao seu .zshrc.
curl -fsSL https://bun.sh/install | bashAbra um terminal novo e confirme:
bun --versionInstale o Docker
Serve para rodar o banco de dados e o Redis. Em vez do Docker Desktop, que é pesado e precisa ficar aberto, o Colima faz o mesmo pela linha de comando.
brew install colima docker docker-composeO Compose vem como plugin e precisa ser apontado ao Docker:
mkdir -p ~/.docker
echo '{"cliPluginsExtraDirs":["/opt/homebrew/lib/docker/cli-plugins"]}' \
> ~/.docker/config.jsonLigue a máquina virtual. Da primeira vez ela baixa uma imagem, então demora um pouco.
colima startdocker compose version deve responder com um número de versão.
Montando o projeto
Baixar o código, configurar e subir os serviços.
Clone o repositório
git clone https://github.com/opencut-app/opencut-classic.git
cd opencut-classicCrie o arquivo de configuração
O exemplo já vem com valores que combinam com o Docker do projeto. Só falta gerar a chave de autenticação, que não pode ficar com o texto de exemplo.
cp apps/web/.env.example apps/web/.env.local
sed -i '' "s|BETTER_AUTH_SECRET=your_better_auth_secret|BETTER_AUTH_SECRET=$(openssl rand -base64 32)|" \
apps/web/.env.localgrep BETTER_AUTH_SECRET apps/web/.env.local deve mostrar uma sequência aleatória.
Suba o banco e o Redis
São três containers. Na primeira vez o Docker baixa as imagens.
docker compose up -d db redis serverless-redis-httpdocker compose ps deve listar os três como healthy.
Instale as dependências
São cerca de 1.900 pacotes, mas o Bun resolve em menos de um minuto.
bun install
Você não precisa compilar nada de Rust. O app usa o pacote opencut-wasm já
publicado; compilar só é necessário se você for mexer no código Rust do projeto.
Crie as tabelas do banco
cd apps/web
bun run db:migrate
cd ../..Ligando
O último passo antes de abrir o editor — e um ajuste que faz toda a diferença.
Desligue o overlay de depuração
Este passo não está na documentação, mas sem ele o editor é inutilizável: o projeto carrega o react-scan automaticamente em modo de desenvolvimento, que pinta caixas roxas piscando sobre cada elemento da tela a cada clique.
Em apps/web/src/app/layout.tsx, por volta da linha 32, troque a condição:
- {process.env.NODE_ENV === "development" && (
+ {process.env.NEXT_PUBLIC_REACT_SCAN === "true" && (
E, em apps/web/next.config.ts, acrescente uma linha dentro de
nextConfig para remover também o distintivo do Next.js no canto da tela:
devIndicators: false,
Para trazer o react-scan de volta algum dia, basta pôr NEXT_PUBLIC_REACT_SCAN=true
no .env.local.
Inicie o servidor
bun run dev:webAbra http://localhost:3000 no navegador, clique em Try early beta e depois em Create your first project.
Quando algo trava
Os três problemas que aparecem com mais frequência, e o que fazer.
“Unable to acquire lock” ou a porta 3000 ocupada
Acontece quando um servidor anterior não morreu direito.
pkill -f "next dev"
pkill -f "turbo run dev"
rm -f apps/web/.next/dev/lockDepois é só rodar bun run dev:web de novo.
“Cannot connect to the Docker daemon”
A máquina virtual do Colima não está ligada — ela não sobe sozinha depois que você reinicia o Mac.
colima startPara que ela suba junto com o sistema: brew services start colima.
O editor abre, mas a tela toda pisca ao clicar
É o react-scan do passo 8. Se você pulou aquele passo, volte nele.
Depois de editar o next.config.ts é preciso reiniciar o servidor — mudanças
nesse arquivo não recarregam sozinhas.
Rodando tudo em Docker
Alternativa se você não quer instalar Bun nem mexer no código.
→ Modo self-hosted
Sobe o app já compilado junto com o banco, num comando só. Em compensação, você perde o recarregamento automático e não consegue aplicar o ajuste do passo 8.
docker compose up -dDisponível em http://localhost:3100 — repare que a porta é outra.