Ir para o conteúdo principal

Desenvolvimento com Contêineres Dev

Os Contêineres Dev fornecem um ambiente de desenvolvimento consistente e reproduzível usando contêineres Docker. Com um único clique, você pode iniciar um ambiente de desenvolvimento Immich no Mac, Linux, Windows ou na nuvem usando o GitHub Codespaces.

Inicie rapidamente!

Abrir no GitHub Codespaces

Saiba mais sobre Contêineres Dev

Pré-requisitos​

Antes de começar, certifique-se de ter:

  • Docker Desktop (versão mais recente)
  • Visual Studio Code com a extensão Dev Containers
  • Git para clonar o repositório
  • Pelo menos 8GB de RAM (16GB recomendados)
  • 20GB de espaço livre em disco
Ambientes de Desenvolvimento Alternativos

Embora este guia foque no VS Code, você tem muitas opções para desenvolvimento com Contêiner Dev:

Editores Locais:

Soluções Baseadas na Nuvem:

  • GitHub Codespaces - Totalmente integrado ao GitHub, suporte excelente para devcontainer.json
  • GitPod - Plataforma SaaS com suporte recente para contêineres Dev (historicamente usava gitpod.yml)

Opções Auto-Hospedadas:

  • Coder - Focado em empresas, requer conhecimento em Terraform, autogerenciado
  • DevPod - Ferramenta somente cliente com excelente suporte a devcontainer.json, funciona com qualquer provedor (local, nuvem ou no local)

Serviços do Contêiner Dev​

O ambiente do Contêiner Dev consiste nos seguintes serviços:

ServiçoNome do ContêinerDescriçãoPortas
Servidor & Webimmich-serverExecuta o servidor de API e o frontend web em modo de desenvolvimento2283 (API)
3000 (Web)
9230 (Depuração de Workers)
9231 (Depuração de API)
Banco de DadosdatabaseBanco de dados PostgreSQL5432
CacheredisServidor de cache Valkey6379
Aprendizado de Máquinaimmich-machine-learningServidor de inferência de modelo ML do Immich3003

Primeiros Passos​

Etapa 1: Clonar o Repositório​

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

Etapa 2: Configurar Variáveis de Ambiente​

Os contêineres dev do Immich leem variáveis de ambiente do seu ambiente shell, não de arquivos .env. Isso permite que eles funcionem em ambientes na nuvem sem pré-configuração.

Configuração

Ao executar localmente, e se você deseja criar (ou usar uma existente) pasta de armazenamento de fotos e/ou banco de dados, você deve definir a variável UPLOAD_LOCATION em seu ambiente shell antes de iniciar o Contêiner Dev. Isso determina onde os arquivos enviados serão armazenados e também onde o banco de dados salva seus dados.

# Configure temporariamente para a sessão atual
export UPLOAD_LOCATION=/opt/dev_upload_folder

# Ou adicione ao seu perfil do shell para persistência
# (~/.bashrc, ~/.zshrc, ~/.bash_profile, etc.)
echo 'export UPLOAD_LOCATION=/opt/dev_upload_folder' >> ~/.bashrc
source ~/.bashrc

Etapa 3: Iniciar o Contêiner Dev​

dica

O desenvolvimento do Immich faz uso extensivo de imagens base especializadas para seu desenvolvimento baseado em docker-compose. Por esse motivo, você não poderá usar o comando Clone Repository in a Container Volume do VSCode.

Usando a Interface do VS Code:​

  1. Abra o repositório clonado no VS Code
  2. Pressione F1 ou Ctrl/Cmd+Shift+P para abrir o painel de comandos
  3. Digite e selecione "Dev Containers: Rebuild and Reopen in Container"
  4. Selecione "Immich - Backend, Frontend and ML" da lista
  5. Aguarde o contêiner ser construído e iniciado (isso pode levar vários minutos na primeira execução)

Usando Ações Rápidas do VS Code:​

  1. Abra o repositório no VS Code
  2. Você verá uma popup perguntando se deseja reabrir em um contêiner
  3. Clique em "Reabrir em Contêiner"

Usando Linha de Comando:​

# Usando o CLI DevContainer
devcontainer up --workspace-folder .

Detalhes das Variáveis de Ambiente​

Como Contêineres Dev Lidam com Variáveis de Ambiente​

Diferentemente da configuração de desenvolvedor do Immich baseada em Docker Compose que usa arquivos .env, os Contêineres Dev do Immich leem variáveis de ambiente do seu ambiente shell. Isso é configurado em .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}"
}

A sintaxe ${localEnv:VARIABLE:default} lê do seu ambiente shell com valores padrão opcionais.

Resolução do Caminho de Upload Location​

A variável de ambiente UPLOAD_LOCATION controla onde os arquivos são armazenados:

Padrão: ./Library (relativo ao diretório docker) Resolvido para: <immich-root>/docker/Library

Montagens Bind Criadas:

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

Configuração do Banco de Dados​

Essas variáveis têm valores padrão apropriados (para desenvolvimento) mas podem ser personalizadas:

VariávelPadrãoDescrição
DB_PASSWORDpostgresSenha do PostgreSQL
DB_USERNAMEpostgresNome de usuário do PostgreSQL
DB_DATABASE_NAMEimmichNome do banco de dados

Configurando Variáveis de Ambiente​

Adicione-as ao seu perfil shell (~/.bashrc, ~/.zshrc, ~/.bash_profile, etc.):

# Necessário
export UPLOAD_LOCATION=./Library  # ou caminho absoluto

# Opcional (apenas se estiver usando valores diferentes dos padrões)
export DB_PASSWORD=sua_senha
export DB_USERNAME=seu_usuario
export DB_DATABASE_NAME=seu_banco_de_dados

Lembre-se de recarregar sua configuração de shell:

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

Configuração do Git​

Chaves SSH e Autenticação​

Para usar suas chaves SSH para acesso ao GitHub dentro do Contêiner Dev:

  1. Inicie o Agente SSH na sua máquina hospedeira:

    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_rsa  # ou o caminho da sua chave

  2. O VS Code encaminha automaticamente seu agente SSH para o contêiner

Para instruções detalhadas, veja o guia do VS Code sobre compartilhamento de credenciais Git.

Assinatura de Commit​

Para usar sua chave SSH para assinatura de commits, veja o guia do GitHub sobre assinatura SSH de commits.

Fluxo de Trabalho de Desenvolvimento​

Configuração Automática​

Quando o Contêiner Dev inicia, ele automaticamente:

  1. Executa script pós-criação (container-server-post-create.sh):

    • Ajusta permissões de arquivo para o usuário node
    • Instala dependências: npm install em todos os pacotes
    • Compila SDK TypeScript: npm run build em open-api/typescript-sdk

  2. Inicia servidores de desenvolvimento via tarefas do VS Code:

    • Immich API Server (Nest) - Servidor de API com recarga automática na porta 2283
    • Immich Web Server (Vite) - Frontend web com recarga automática na porta 3000
    • Ambos servidores observam alterações nos arquivos e recompilam automaticamente

  3. Configura encaminhamento de portas:

informação

A configuração do Contêiner Dev substitui o comando make dev da configuração tradicional. Todos os serviços iniciam automaticamente ao abrir o contêiner.

Acessando Serviços​

Uma vez em execução, você pode acessar:

ServiçoURLDescrição
UI Webhttp://localhost:3000Interface web principal
APIhttp://localhost:2283Endpoints REST API (Não usado diretamente, a UI web exporá isso em http://localhost:3000/api)
Banco de Dadoslocalhost:5432PostgreSQL (usuário: postgres) (Não usado diretamente)

Conectando Aplicativos Móveis​

Para conectar o aplicativo móvel ao seu Contêiner Dev:

  1. Encontre o endereço IP da sua máquina
  2. No aplicativo móvel, use: http://SEU_IP:3000/api
  3. Certifique-se de que seu firewall permite conexões na porta 2283

Fazendo Alterações no Código​

  • Código do servidor (/server): As alterações acionam reinício automático
  • Código da Web (/web): As alterações acionam substituição de módulo a quente
  • Migrações de Banco de Dados: Execute npm run sync:sql no diretório do servidor
  • Alterações na API: Regenerar SDK TypeScript com make open-api

Testando​

Executando Testes​

O Container de Desenvolvimento suporta várias formas de executar testes:

Usando Comandos Make (Recomendado)​

# Execute testes para componentes específicos
make test-server         # Testes unitários do servidor
make test-web           # Testes unitários da web
make test-e2e           # Testes de ponta a ponta
make test-cli           # Testes da CLI

# Execute todos os testes
make test-all           # Executa testes para todos os componentes

# Testes médios (testes de integração)
make test-medium-dev    # Testes de ponta a ponta

Usando NPM Diretamente​

# Testes do servidor
cd /workspaces/immich/server
npm test                # Executa todos os testes
npm run test:watch     # Modo de observação
npm run test:cov       # Relatório de cobertura

# Testes da web
cd /workspaces/immich/web
npm test               # Executa todos os testes
npm run test:watch     # Modo de observação

# Testes E2E
cd /workspaces/immich/e2e
npm run test           # Executa testes de API
npm run test:web       # Executa testes de IU da web

Comandos de Qualidade de Código​

# Linting
make lint-server        # Analisa o código do servidor
make lint-web          # Analisa o código da web
make lint-all          # Analisa todos os componentes

# Formatação
make format-server      # Formata o código do servidor
make format-web        # Formata o código da web
make format-all        # Formata todo o código

# Verificação de tipos
make check-server       # Verifica tipos do servidor
make check-web         # Verifica tipos da web
make check-all         # Verifica todos os componentes

# Verificação completa de higiene
make hygiene-all       # Executa lint, formata, verifica, sincroniza SQL e audita

Comandos Make Adicionais​

# Comandos de build
make build-server       # Build do servidor
make build-web         # Build da aplicação web
make build-all         # Build de tudo

# Geração de API
make open-api          # Gera especificações OpenAPI
make open-api-typescript # Gera SDK TypeScript
make open-api-dart     # Gera SDK Dart

# Banco de dados
make sql               # Sincroniza esquema do banco de dados

# Dependências
make install-server    # Instala dependências do servidor
make install-web      # Instala dependências da web
make install-all      # Instala todas as dependências

Depuração​

O Container de Desenvolvimento está pré-configurado para depuração:

  1. Depuração do Servidor de API:

    • Configure pontos de interrupção no VS Code
    • Pressione F5 ou use o painel "Executar e Depurar"
    • Selecione a configuração "Attach to Server"
    • Porta de depuração: 9231

  2. Depuração do Worker:

    • Use a configuração "Attach to Workers"
    • Porta de depuração: 9230

  3. Depuração da Web:

    • Use DevTools do navegador
    • Depurador do VS Code para extensões Chrome/Edge suportado

Solução de Problemas​

Problemas Comuns​

Erros de Permissão​

Problema: Erros EACCES ou permissão negada
Solução:

  • O Container de Desenvolvimento é executado como o usuário node (UID 1000)
  • Caso o UID do host seja diferente, você pode enfrentar problemas de permissão
  • Tente reconstruir o container: "Containers de Desenvolvimento: Reconstruir Container"

Container Não Inicia​

Problema: O Container de Desenvolvimento falha ao iniciar ou construir
Solução:

  1. Verifique se o Docker está em execução: docker ps
  2. Limpe recursos do Docker: docker system prune -a
  3. Verifique o espaço disponível em disco
  4. Revise os limites de recursos do Docker Desktop

Porta Já em Uso​

Problema: "Porta 3000/2283 já está em uso"
Solução:

  1. Verifique serviços conflitantes: lsof -i :3000 (macOS/Linux)
  2. Pare serviços conflitantes ou altere os mapeamentos de porta
  3. Reinicie o Docker Desktop

Localização de Upload Não Configurada​

Problema: Erros relacionados à ausência de UPLOAD_LOCATION
Solução:

  1. Configure a variável de ambiente: export UPLOAD_LOCATION=./Library
  2. Adicione ao perfil de shell para persistência
  3. Reinicie seu terminal e o VS Code

Falha na Conexão com o Banco de Dados​

Problema: Não é possível conectar ao PostgreSQL
Solução:

  1. Certifique-se de que todos os containers estão ativos: docker ps
  2. Verifique os logs: "Containers de Desenvolvimento: Mostrar Logs do Container"
  3. Verifique se as credenciais do banco de dados correspondem às variáveis de ambiente

Obtendo Ajuda​

Se encontrar problemas:

  1. Verifique os logs do container: Visualizar → Saída → Selecione "Containers de Desenvolvimento"
  2. Reconstrua sem cache: "Containers de Desenvolvimento: Reconstruir Container Sem Cache"
  3. Revise problemas comuns do Docker
  4. Pergunte no Discord no canal #help-desk-support

Desenvolvimento Mobile​

Embora o Container de Desenvolvimento seja focado em desenvolvimento de servidor e web, você pode conectar apps mobile para testes:

Conectando Apps iOS/Android​

  1. Certifique-se de que a API está acessível:

    # Descubra o IP da sua máquina
    # macOS
    ipconfig getifaddr en0
    # Linux
    hostname -I
    # Windows (no WSL2)
    ip addr show eth0

  2. Configure o app mobile:

    • URL do servidor: http://SEU_IP:2283/api
    • Certifique-se de que o firewall permite a porta 2283

  3. Para desenvolvimento mobile completo, veja o guia de desenvolvimento mobile, que cobre:

    • Configuração do Flutter
    • Execução em simuladores/dispositivos
    • Depuração específica para mobile

Configuração Avançada​

Extensões Personalizadas do VS Code​

Adicione extensões ao .devcontainer/devcontainer.json:

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

Serviços Adicionais​

Para adicionar serviços (por exemplo, Redis Commander), modifique:

  1. /docker/docker-compose.dev.yml - Adicione a definição do serviço
  2. /.devcontainer/server/container-compose-overrides.yml - Adicione substituições, se necessário

Limites de Recursos​

Ajuste os recursos do Docker Desktop:

  • macOS/Windows: Docker Desktop → Configurações → Recursos
  • Linux: Modifique a configuração do daemon do Docker

Mínimos recomendados:

  • CPU: 4 núcleos
  • Memória: 8GB
  • Disco: 20GB

Próximos Passos​