RomanNum3ral
/
OpenCut
mirror of https://github.com/OpenCut-app/OpenCut.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
OpenCut/setup-steps.md

12 KiB
Raw Blame History

Setup Steps - NeuralCut (Windows)

Guia paso a paso para levantar el proyecto desde cero en Windows. Si es tu primer proyecto de software, no te preocupes: cada paso esta explicado.

Antes de empezar: Abrí PowerShell como Administrador (click derecho en el menu Inicio > "Terminal (Administrador)" o "Windows PowerShell (Administrador)"). Vas a necesitarlo para todos los pasos de instalacion.

Indice

  1. Instalar herramientas base (Git + Node.js + Docker)
  2. Instalar Bun
  3. Clonar el repositorio
  4. Configurar variables de entorno
  5. Levantar la base de datos con Docker
  6. Instalar dependencias del proyecto
  7. Correr migraciones de la base de datos
  8. Iniciar el servidor de desarrollo
  9. Configurar VS Code
  10. Comandos utiles
  11. Instalar y usar opencode

1. Instalar herramientas base

Vamos a instalar todo de una con winget, el gestor de paquetes que ya viene en Windows. Abrí PowerShell como Administrador y ejecuta estos tres comandos:

winget install Git.Git --accept-source-agreements --accept-package-agreements

winget install OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements

winget install Docker.DockerDesktop --accept-source-agreements --accept-package-agreements

Que son estas herramientas?

  • Git: Control de versiones. Permite que varias personas trabajen en el mismo codigo sin pisarse.
  • Node.js: Entorno para ejecutar JavaScript fuera del navegador. Incluye npm automaticamente.
  • Docker Desktop: Permite correr servicios (base de datos, Redis) en contenedores sin instalarlos a mano.

Cada uno se baja e instala solo. Cuando terminen los tres, cierra la terminal y abri una nueva (no hace falta que sea admin esta vez). Verifica que anden:

git --version
node --version
npm --version
docker --version

Si los cuatro te muestran numeros de version, todo bien.

Configura tu identidad en Git (necesario para hacer commits):

git config --global user.name "Tu Nombre"
git config --global user.email "tu@email.com"

Si winget no existe (muy poco probable en Windows 10/11): Instalá cada herramienta manualmente desde sus webs: Git, Node.js LTS, Docker Desktop.

Si Docker no arranca despues de instalarlo, saltea a Solucion de problemas de Docker.

2. Instalar Bun

Bun es el gestor de paquetes que usa este proyecto (es mas rapido que npm). Se instala con npm:

npm install -g bun

Verifica:

bun --version

Deberias ver algo como 1.2.x.

3. Clonar el repositorio

Clonar significa descargar una copia del codigo fuente a tu computadora.

  1. Navega a la carpeta donde quieras guardar el proyecto:
cd C:\Users\TuUsuario\Documents
  1. Clona el repo:
git clone https://github.com/TU-USUARIO/NeuralCut.git

OJO: Reemplaza TU-USUARIO con el usuario/organizacion correcta del repositorio. Si te dieron un fork propio, usa tu usuario.

  1. Entra a la carpeta del proyecto:
cd NeuralCut

4. Configurar variables de entorno

Las variables de entorno son configuraciones que la aplicacion necesita para funcionar (conexion a la base de datos, claves secretas, etc.).

El proyecto tiene un archivo de ejemplo con los valores por defecto. Copialo:

Copy-Item apps\web\.env.example apps\web\.env.local

El .env.example ya tiene valores por defecto que coinciden con la configuracion de Docker. Para desarrollo local deberia funcionar tal cual. No cambies los valores a menos que sepas lo que haces.

5. Levantar la base de datos con Docker

Antes de continuar: Abri Docker Desktop desde el menu Inicio y espera a que diga "Docker Desktop is running" (el icono de la ballena en la barra de tareas deja de animarse). Esto puede tardar un minuto la primera vez.

Desde la raiz del proyecto, ejecuta:

docker compose up -d db redis serverless-redis-http

Esto levanta tres servicios:

  • db: Base de datos PostgreSQL (puerto 5432)
  • redis: Cache en memoria (puerto 6379)
  • serverless-redis-http: Interfaz HTTP para Redis (puerto 8079)

Verifica que esten corriendo:

docker compose ps

Deberias ver tres servicios con estado Up o healthy.

Para detener los contenedores cuando termines de trabajar: docker compose down

Para detener y borrar los datos: docker compose down -v (solo si queres empezar de cero)

6. Instalar dependencias del proyecto

Las dependencias son librerias externas que el proyecto necesita para funcionar (React, Next.js, etc.).

bun install

Esto lee el package.json y descarga todo. Puede tardar un par de minutos la primera vez. Si no hay errores rojos, todo bien (algunos warnings amarillos son normales).

Si falla: Prueba borrar node_modules y bun.lock y volver a correr bun install.

7. Correr migraciones de la base de datos

Las migraciones crean las tablas y estructuras necesarias en la base de datos.

Asegurate de que Docker este corriendo (paso 5) y ejecuta:

bun run db:migrate

Si dice "no migrations to apply": No pasa nada, significa que ya estan aplicadas o que se aplicaran automaticamente.

8. Iniciar el servidor de desarrollo

bun dev:web

Espera a que veas algo como:

  ▲ Next.js 16.x.x
  - Local:   http://localhost:3000

Abre tu navegador en http://localhost:3000. Deberias ver la aplicacion corriendo. Listo!

Para detener el servidor: Presiona Ctrl + C en la terminal.

9. Configurar VS Code (recomendado)

Si no tenes VS Code, instalalo con winget:

winget install Microsoft.VisualStudioCode --accept-source-agreements --accept-package-agreements

El proyecto ya tiene configuracion de VS Code en .vscode/settings.json. Para que funcione bien, instala estas extensiones:

Obligatoria

  1. Biome - Linter y formateador del proyecto. Corrige errores de codigo y formatea automaticamente al guardar.

Recomendadas

  1. Tailwind CSS IntelliSense - Autocompletado de clases CSS
  2. Error Lens - Muestra errores inline directamente en el editor
  3. GitLens - Muestra quien escribio cada linea de codigo y cuando

Para instalar extensiones: abri VS Code, anda a la barra lateral izquierda (icono de cuadrados), busca cada extension por nombre y dale "Install".

10. Comandos utiles

Los comandos que van a usar dia a dia, desde la raiz del proyecto:

Comando Que hace
bun dev:web Inicia el servidor de desarrollo
bun run build:web Compila el proyecto para produccion
bun run lint:web Revisa errores de codigo
bun run lint:web:fix Revisa y corrige errores automaticamente
bun run format:web Formatea el codigo
bun run db:migrate Aplica migraciones de base de datos
docker compose up -d Levanta los servicios de Docker
docker compose down Detiene los servicios de Docker

11. Instalar y usar opencode

opencode es una herramienta de IA que te ayuda a escribir codigo, resolver bugs y navegar el proyecto directo desde la terminal.

Instalacion

npm install -g opencode

Verifica:

opencode --version

Configuracion inicial

opencode necesita una API key de un proveedor de IA. Preguntale al equipo cual usar y te pasan la config.

Como usarlo

Desde la raiz del proyecto:

opencode

Se abre una interfaz interactiva en la terminal. Ahi podes:

  • Preguntar sobre el codigo: "Explicame que hace el archivo apps/web/src/app/page.tsx"
  • Pedir cambios: "Agrega un boton que diga Hola en la pagina principal"
  • Buscar bugs: "Revisa por que falla el login"
  • Buscar archivos: "Donde esta el componente del timeline?"

Para salir: Ctrl + C o /exit

Comando Que hace
/help Muestra la ayuda completa
/exit Sale de opencode
/compact Compacta la conversacion para ahorrar contexto

Tip: opencode lee el archivo AGENTS.md del proyecto para entender las convenciones. No hace falta que le expliques la arquitectura cada vez.

Resumen rapido (para cuando ya lo configuraste una vez)

# 1. Abrir Docker Desktop manualmente

# 2. Levantar servicios
docker compose up -d db redis serverless-redis-http

# 3. Iniciar el servidor
bun dev:web

# 4. Abrir http://localhost:3000 en el navegador

# 5. Cuando termines de trabajar
# Ctrl+C en la terminal del servidor
docker compose down

Solucion de problemas de Docker en Windows

Docker Desktop en Windows necesita virtualizacion (hardware) y WSL 2 (Windows). Si Docker tira un error al iniciar, segui estos pasos.

Paso 1: Verificar virtualizacion

  1. Abri Administrador de tareas (Ctrl + Shift + Esc)
  2. Pestaña Rendimiento > CPU
  3. Busca Virtualización: Habilitada

Si dice Deshabilitada, hay que habilitarla en el BIOS:

  1. Reinicia la compu y presiona repetidamente la tecla para entrar al BIOS:
    • HP: F10 o Esc
    • Lenovo: F2 o Fn + F2
    • Dell: F2
    • ASUS: F2 o Supr
    • Acer: F2 o Supr
  2. Busca alguna de estas opciones (suele estar en Advanced > CPU Configuration o Security):
    • Intel Virtualization Technology / Intel VT-x (Intel)
    • SVM Mode / AMD-V (AMD)
  3. Cambiala a Enabled
  4. Guarda y sali (generalmente F10)

Paso 2: Habilitar WSL 2

Abri PowerShell como Administrador y ejecuta:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Reinicia la computadora. Despues, abri PowerShell normal y ejecuta:

wsl --set-default-version 2

Si te pide instalar un kernel update, bajalo de https://aka.ms/wsl2kernel y ejecutalo.

Verifica con wsl --status — deberia decir Default Version: 2.

Paso 3: Reiniciar Docker

  1. Abri Docker Desktop
  2. Anda a Settings (engranaje) > General
  3. Asegurate que "Use the WSL 2 based engine" este marcado
  4. Docker deberia arrancar ahora

Si despues de todo sigue sin funcionar, desinstala Docker, reinicia, y vuelve a instalar: winget install Docker.DockerDesktop. Si aun asi falla, hablale a un companero.

Problemas comunes

"winget no se reconoce como un comando"

Tu Windows es muy viejo. Instalá las herramientas manualmente desde sus webs: Git, Node.js LTS, Docker Desktop.

"bun no se reconoce como un comando"

Cerra la terminal y abrila de nuevo. Si persiste, corre npm install -g bun otra vez.

"docker compose up" falla con error de conexion

Asegurate de que Docker Desktop este abierto y mostrando "Docker Desktop is running". Espera unos segundos y vuelve a intentar.

"Error: connect ECONNREFUSED 127.0.0.1:5432"

La base de datos no esta levantada. Corre docker compose up -d db y espera a que diga healthy.

"Next.js build error" o errores de TypeScript

Borra la cache y reinstala:

Remove-Item -Recurse -Force apps\web\.next
bun install
bun dev:web

Los estilos se ven mal o no cargan

Reinicia el servidor: Ctrl+C y bun dev:web de nuevo.

Si llegaste hasta aca y la app corre en http://localhost:3000, estas listo para trabajar. Bienvenido al equipo!