Saltar al contenido principal

Desarrollo con Contenedores de Desarrollo

Los contenedores de desarrollo proporcionan un entorno de desarrollo consistente y reproducible usando contenedores Docker. Con un solo clic, puedes comenzar con un entorno de desarrollo de Immich en Mac, Linux, Windows o en la nube utilizando GitHub Codespaces.

¡Comienza rápidamente!

Abrir en GitHub Codespaces

Aprende más sobre Contenedores de Desarrollo

Prerrequisitos​

Antes de comenzar, asegúrate de tener:

  • Docker Desktop (última versión)
  • Visual Studio Code con la extensión Dev Containers
  • Git para clonar el repositorio
  • Al menos 8GB de RAM (16GB recomendados)
  • 20GB de espacio libre en disco
Entornos de Desarrollo Alternativos

Aunque esta guía se centra en Visual Studio Code, tienes varias opciones para el desarrollo con Contenedores de Desarrollo:

Editores Locales:

Soluciones Basadas en la Nube:

  • GitHub Codespaces - Totalmente integrado con GitHub, excelente soporte para devcontainer.json
  • GitPod - Plataforma SaaS con soporte reciente para Contenedores de Desarrollo (históricamente usaba gitpod.yml)

Opciones Auto-gestionadas:

  • Coder - Enfocado en empresas, requiere conocimientos de Terraform, auto-gestionado
  • DevPod - Herramienta únicamente para el cliente con excelente soporte para devcontainer.json, funciona con cualquier proveedor (local, nube o en las instalaciones)

Servicios de Contenedores de Desarrollo​

El entorno de Contenedores de Desarrollo consta de los siguientes servicios:

ServicioNombre del ContenedorDescripciónPuertos
Servidor y Webimmich-serverEjecuta tanto el servidor API como el frontend web en modo desarrollo2283 (API)
3000 (Web)
9230 (Depuración de Trabajadores)
9231 (Depuración de API)
Base de DatosdatabaseBase de datos PostgreSQL5432
CachéredisServidor de caché Valkey6379
Aprendizaje Automáticoimmich-machine-learningServidor de inferencia del modelo de aprendizaje automático de Immich3003

Primeros Pasos​

Paso 1: Clonar el Repositorio​

git clone https://github.com/immich-app/immich.git
cd immich

Paso 2: Configurar Variables de Entorno​

Los contenedores de desarrollo de Immich leen las variables de entorno de tu entorno shell, no de archivos .env. Esto les permite operar en entornos en la nube sin preconfiguración.

Configuración

Cuando se ejecuta localmente, y si deseas crear (o usar una existente) carpeta de base de datos y/o almacenamiento de fotos, debes establecer la variable UPLOAD_LOCATION en tu entorno shell antes de iniciar el Contenedor de Desarrollo. Esto determina dónde se almacenan los archivos subidos y también dónde la base de datos almacena sus datos.

# Configuración Temporal para la Sesión Actual
export UPLOAD_LOCATION=/opt/dev_upload_folder

# O agrégala a tu perfil de shell para persistencia
# (~/.bashrc, ~/.zshrc, ~/.bash_profile, etc.)
echo 'export UPLOAD_LOCATION=/opt/dev_upload_folder' >> ~/.bashrc
source ~/.bashrc

Paso 3: Iniciar el Contenedor de Desarrollo​

consejo

El desarrollo de Immich utiliza extensivamente imágenes base especializadas para su configuración basada en docker-compose. Por esta razón, no podrás usar el comando Clonar Repositorio en un Volumen de Contenedor de VSCode.

Usando la Interfaz de Usuario de VS Code:​

  1. Abre el repositorio clonado en VS Code
  2. Presiona F1 o Ctrl/Cmd+Shift+P para abrir la paleta de comandos
  3. Escribe y selecciona "Dev Containers: Rebuild and Reopen in Container"
  4. Selecciona "Immich - Backend, Frontend and ML" de la lista
  5. Espera a que el contenedor se construya e inicie (esto puede tomar varios minutos en la primera ejecución)

Usando Acciones Rápidas de VS Code:​

  1. Abre el repositorio en VS Code
  2. Debes ver un popup preguntando si deseas reabrir en un contenedor
  3. Haz clic en "Reopen in Container"

Usando la Línea de Comandos:​

# Usando el CLI de DevContainer
devcontainer up --workspace-folder .

Detalles de las Variables de Entorno​

Cómo los Contenedores de Desarrollo Manejan Variables de Entorno​

A diferencia de la configuración de desarrollo de Immich basada en Docker Compose que utiliza archivos .env, los Contenedores de Desarrollo de Immich leen las variables de entorno de tu entorno shell. Esto se configura en .devcontainer/devcontainer.json:

"remoteEnv": {
    "UPLOAD_LOCATION": "${localEnv:UPLOAD_LOCATION:./Library}",
    "DB_PASSWORD": "${localEnv:DB_PASSWORD:postgres}",
    "DB_USERNAME": "${localEnv:DB_USERNAME:postgres}",
    "DB_DATABASE_NAME": "${localEnv:DB_DATABASE_NAME:immich}"
}

La sintaxis ${localEnv:VARIABLE:default} lee de tu entorno shell con valores predeterminados opcionales.

Resolución de la Ruta de UPLOAD_LOCATION​

La variable de entorno UPLOAD_LOCATION controla dónde se almacenan los archivos:

Predeterminado: ./Library (relativo al directorio docker) Resuelto en: <immich-root>/docker/Library

Montajes Vinculados Creados:

# Desde .devcontainer/server/container-compose-overrides.yml
- ${UPLOAD_LOCATION-./Library}/photos:/workspaces/immich/server/upload
- ${UPLOAD_LOCATION-./Library}/postgres:/var/lib/postgresql/data

Configuración de la Base de Datos​

Estas variables tienen valores predeterminados sensatos (para desarrollo) pero pueden personalizarse:

VariablePredeterminadoDescripción
DB_PASSWORDpostgresContraseña de PostgreSQL
DB_USERNAMEpostgresNombre de usuario de PostgreSQL
DB_DATABASE_NAMEimmichNombre de la base de datos

Configuración de Variables de Entorno​

Añade estas a tu perfil de shell (~/.bashrc, ~/.zshrc, ~/.bash_profile, etc.):

# Obligatorio
export UPLOAD_LOCATION=./Library  # o ruta absoluta

# Opcional (solo si usas valores no predeterminados)
export DB_PASSWORD=your_password
export DB_USERNAME=your_username
export DB_DATABASE_NAME=your_database

Recuerda recargar tu configuración de shell:

source ~/.bashrc  # o ~/.zshrc, etc.

Configuración de Git​

Claves SSH y Autenticación​

Para usar tus claves SSH para el acceso a GitHub dentro del Contenedor de Desarrollo:

  1. Inicia el Agente SSH en tu máquina anfitriona:

    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_rsa  # o la ruta de tu clave

  2. VS Code reenvía automáticamente tu agente SSH al contenedor

Para instrucciones detalladas, consulta la guía de VS Code sobre compartir credenciales de Git.

Firmado de Commits​

Para usar tu clave SSH para firmar commits, consulta la guía de GitHub sobre firmado de commits con SSH.

Flujo de Trabajo de Desarrollo​

Configuración Automática​

Cuando el Contenedor de Desarrollo se inicia, automáticamente:

  1. Ejecuta el script post-creación (container-server-post-create.sh):

    • Ajusta los permisos de los archivos para el usuario node
    • Instala dependencias: npm install en todos los paquetes
    • Construye el SDK de TypeScript: npm run build en open-api/typescript-sdk

  2. Inicia los servidores de desarrollo a través de tareas de VS Code:

    • Servidor API de Immich (Nest) - Servidor API con recarga en caliente en el puerto 2283
    • Servidor Web de Immich (Vite) - Frontend web con recarga en caliente en el puerto 3000
    • Ambos servidores observan cambios en los archivos y se recompilan automáticamente

  3. Configura el reenvío de puertos:

información

La configuración del Contenedor de Desarrollo reemplaza el comando make dev de la configuración tradicional. Todos los servicios se inician automáticamente cuando abres el contenedor.

Acceso a Servicios​

Una vez en ejecución, puedes acceder a:

ServicioURLDescripción
Interfaz Webhttp://localhost:3000Interfaz web principal
APIhttp://localhost:2283Endpoints REST API (No se usa directamente, la interfaz web expondrá esto en http://localhost:3000/api)
Base de Datoslocalhost:5432PostgreSQL (nombre de usuario: postgres) (No se usa directamente)

Conectando Aplicaciones Móviles​

Para conectar la aplicación móvil con tu Contenedor de Desarrollo:

  1. Encuentra la dirección IP de tu máquina
  2. En la aplicación móvil, usa: http://TU_IP:3000/api
  3. Asegúrate de que tu firewall permita conexiones al puerto 2283

Realizando Cambios en el Código​

  • Código del servidor (/server): Los cambios desencadenan un reinicio automático
  • Código web (/web): Los cambios desencadenan reemplazo de módulos en caliente
  • Migraciones de base de datos: Ejecuta npm run sync:sql en el directorio del servidor
  • Cambios en la API: Regenera el SDK de TypeScript con make open-api

Pruebas​

Ejecución de Pruebas​

El Contenedor de Desarrollo soporta múltiples maneras de ejecutar pruebas:

Usando Comandos Make (Recomendado)​

# Ejecutar pruebas para componentes específicos
make test-server         # Pruebas unitarias del servidor
make test-web           # Pruebas unitarias de la web
make test-e2e           # Pruebas de extremo a extremo
make test-cli           # Pruebas de CLI

# Ejecutar todas las pruebas
make test-all           # Ejecuta pruebas para todos los componentes

# Pruebas de integración
make test-medium-dev    # Pruebas de extremo a extremo

Usando NPM Directamente​

# Pruebas del servidor
cd /workspaces/immich/server
npm test                # Ejecutar todas las pruebas
npm run test:watch     # Modo de vigilancia
npm run test:cov       # Informe de cobertura

# Pruebas de la web
cd /workspaces/immich/web
npm test               # Ejecutar todas las pruebas
npm run test:watch     # Modo de vigilancia

# Pruebas E2E
cd /workspaces/immich/e2e
npm run test           # Ejecutar pruebas de API
npm run test:web       # Ejecutar pruebas de la interfaz web

Comandos de Calidad de Código​

# Linter
make lint-server        # Revisión del código del servidor
make lint-web          # Revisión del código de la web
make lint-all          # Revisión de todos los componentes

# Formateado
make format-server      # Formatear código del servidor
make format-web        # Formatear código de la web
make format-all        # Formatear todo el código

# Verificación de Tipos
make check-server       # Verificar tipos en el servidor
make check-web         # Verificar tipos en la web
make check-all         # Verificar todos los componentes

# Verificación Completada
make hygiene-all       # Ejecuta linter, formateador, check, sync de SQL y auditoría

Comandos Adicionales Make​

# Comandos de construcción
make build-server       # Construir servidor
make build-web         # Construir aplicación web
make build-all         # Construir todo

# Generación de API
make open-api          # Generar especificaciones OpenAPI
make open-api-typescript # Generar SDK de TypeScript
make open-api-dart     # Generar SDK de Dart

# Base de datos
make sql               # Sincronizar esquemas de base de datos

# Dependencias
make install-server    # Instalar dependencias del servidor
make install-web      # Instalar dependencias de la web
make install-all      # Instalar todas las dependencias

Depuración​

El Contenedor de Desarrollo está preconfigurado para depuración:

  1. Depuración del Servidor API:

    • Establecer puntos de ruptura en VS Code
    • Presiona F5 o usa el panel "Run and Debug"
    • Selecciona la configuración "Attach to Server"
    • Puerto de depuración: 9231

  2. Depuración de Workers:

    • Usa la configuración "Attach to Workers"
    • Puerto de depuración: 9230

  3. Depuración de la Web:

    • Usa las herramientas de desarrollo del navegador
    • Se admite el depurador de VS Code para extensiones de Chrome/Edge

Resolución de Problemas​

Problemas Comunes​

Errores de Permisos​

Problema: Errores EACCES o permiso denegado Solución:

  • El Contenedor de Desarrollo se ejecuta como el usuario node (UID 1000)
  • Si el UID de tu host es diferente, podrías tener problemas de permisos
  • Intenta reconstruir el contenedor: "Dev Containers: Rebuild Container"

El Contenedor No Arranca​

Problema: El Contenedor de Desarrollo no arranca o no se construye Solución:

  1. Verifica que Docker está en ejecución: docker ps
  2. Limpia recursos de Docker: docker system prune -a
  3. Revisa el espacio disponible en el disco
  4. Revisa los límites de recursos en Docker Desktop

Puerto Ya en Uso​

Problema: "El puerto 3000/2283 ya está en uso" Solución:

  1. Revisa servicios en conflicto: lsof -i :3000 (macOS/Linux)
  2. Detén los servicios en conflicto o cambia las asignaciones de puertos
  3. Reinicia Docker Desktop

Ubicación de Carga No Configurada​

Problema: Errores relacionados con UPLOAD_LOCATION Solución:

  1. Configura la variable de entorno: export UPLOAD_LOCATION=./Library
  2. Agrégalo a tu perfil de shell para persistencia
  3. Reinicia tu terminal y VS Code

Conexión a Base de Datos Fallida​

Problema: No se puede conectar a PostgreSQL Solución:

  1. Asegúrate de que todos los contenedores están en ejecución: docker ps
  2. Revisa los logs: "Dev Containers: Show Container Log"
  3. Verifica que las credenciales de la base de datos coincidan con las variables de entorno

Obtener Ayuda​

Si encuentras problemas:

  1. Revisa los logs del contenedor: Vista → Salida → Seleccionar "Dev Containers"
  2. Reconstruye sin caché: "Dev Containers: Rebuild Container Without Cache"
  3. Revisa problemas comunes de Docker
  4. Pregunta en Discord en el canal #help-desk-support

Desarrollo Móvil​

Mientras el Contenedor de Desarrollo se enfoca en el desarrollo del servidor y la web, puedes conectar aplicaciones móviles para pruebas:

Conexión de Apps iOS/Android​

  1. Asegúrate de que la API sea accesible:

    # Encuentra la IP de tu máquina
    # macOS
    ipconfig getifaddr en0
    # Linux
    hostname -I
    # Windows (en WSL2)
    ip addr show eth0

  2. Configura la aplicación móvil:

    • URL del servidor: http://YOUR_IP:2283/api
    • Asegúrate de que el firewall permita el puerto 2283

  3. Para desarrollo móvil completo, consulta la guía de desarrollo móvil que cubre:

    • Configuración de Flutter
    • Ejecución en simuladores/dispositivos
    • Depuración específica para móviles

Configuración Avanzada​

Extensiones Personalizadas de VS Code​

Agrega extensiones a .devcontainer/devcontainer.json:

"customizations": {
  "vscode": {
    "extensions": [
      "your.extension-id"
    ]
  }
}

Servicios Adicionales​

Para agregar servicios (por ejemplo, Redis Commander), modifica:

  1. /docker/docker-compose.dev.yml - Agrega la definición del servicio
  2. /.devcontainer/server/container-compose-overrides.yml - Agrega modificaciones si es necesario

Límites de Recursos​

Ajusta los recursos de Docker Desktop:

  • macOS/Windows: Docker Desktop → Configuración → Recursos
  • Linux: Modifica la configuración del demonio de Docker

Recomendaciones mínimas:

  • CPU: 4 núcleos
  • Memoria: 8GB
  • Disco: 20GB

Próximos Pasos​