# Troubleshooting

Soluções para problemas comuns ao usar o DeployAlly.

# Instalação

# Erro: "Permission denied"

Error: Permission denied while trying to install

Causa: Falta de permissões para instalar em /usr/local/bin/.

Solução:

# Opção 1: Usar sudo
curl -fsSL https://get.deployally.com | sudo bash

# Opção 2: Instalar localmente
curl -Lo ~/.local/bin/deployally https://get.deployally.com/releases/latest/deployally
chmod +x ~/.local/bin/deployally
export PATH="$HOME/.local/bin:$PATH"

# Erro: "Unsupported architecture"

Error: Unsupported architecture: armv7l

Causa: Arquitetura não suportada.

Solução: O DeployAlly suporta apenas:

• Linux x86_64 (amd64)
• Linux arm64 (aarch64)

Para outras arquiteturas, compile do fonte:

git clone https://github.com/devborlot/deployally-client
cd deployally-client
cargo build --release

# Configuração

# Erro: "Config file not found"

Error: Config file not found at ~/.config/deployally/config.toml

Causa: CLI não foi inicializado.

Solução:

deployally init --api-url https://sys.deployally.com --api-key {SUA_KEY}

# Erro: "Invalid API key format"

Error: Invalid API key format. Expected: da_*

Causa: API Key com formato incorreto.

Solução: API Keys devem começar com da_ (produção) ou da_test_ (teste).

Obtenha uma key válida em https://app.deployally.com > Configurações > API Keys.

# Conexão

# Erro: "Failed to connect to API"

Error: Failed to connect to API at https://sys.deployally.com

Causas possíveis:

1. Sem internet: Verifique conexão

   curl -I https://sys.deployally.com/api/v1/health

2. Firewall bloqueando: Libere porta 443/TCP

3. DNS não resolvendo: Teste resolução

   dig sys.deployally.com

4. Proxy não configurado: Configure proxy se necessário

   export HTTPS_PROXY=http://proxy:8080

# Erro: "401 Unauthorized"

Error: API returned 401 Unauthorized

Causas possíveis:

1. Key inválida: Verifique se a key está correta
2. Key revogada: Crie uma nova key no Dashboard
3. Key errada (test/prod): Use a key do ambiente correto

# Deploy

# Erro: "Docker not found"

Error: Docker not found. Please install Docker first.

Causa: Docker não está instalado ou não está no PATH.

Solução:

# Instalar via Implant (recomendado)
curl -fsSL https://get.deployally.com/implant | bash

# Ou instalar manualmente
curl -fsSL https://get.docker.com | bash
sudo usermod -aG docker $USER
# Faça logout e login novamente

# Erro: "Permission denied (docker)"

Error: Got permission denied while trying to connect to Docker

Causa: Usuário não tem permissão para usar Docker.

Solução:

sudo usermod -aG docker $USER
# Faça logout e login novamente

# Erro: "Port already in use"

Error: Port 3306 is already in use

Causa: Outro serviço usando a mesma porta.

Solução:

# Verificar o que está usando a porta
sudo lsof -i :3306

# Opção 1: Parar o serviço conflitante
sudo systemctl stop mysql

# Opção 2: Usar porta diferente no deploy
deployally deploy --species mysql --port 3307

# Erro: "Template not found"

Error: Template mysql:9.0 not found

Causa: Template ou versão não existe.

Solução:

# Listar templates disponíveis
deployally list --species mysql

# Erro: "Definition already exists"

Error: Definition with name mysql_meu_banco already exists

Causa: Já existe uma definition com esse nome.

Solução:

# Usar nome diferente
deployally deploy --species mysql --name mysql_outro_banco

# Ou remover a existente
deployally definitions delete mysql_meu_banco

# Containers

# Container não inicia

Verificar logs:

deployally instances logs {nome}

Causas comuns:

1. Falta de memória:

   free -h
   docker stats --no-stream

2. Volume com permissões erradas:

   ls -la /var/lib/docker/volumes/{volume}/_data

3. Configuração inválida: Verifique parâmetros da definition

# Container unhealthy

STATUS: unhealthy

Verificar health check:

docker inspect {container} --format='{{json .State.Health}}'

Causas comuns:

1. Serviço ainda iniciando: Aguarde alguns segundos
2. Porta não respondendo: Verifique logs
3. Recursos insuficientes: Aumente memória/CPU

# Container reiniciando constantemente

STATUS: restarting

Verificar logs:

docker logs --tail 100 {container}

Causas comuns:

1. Crash na inicialização: Erro de configuração
2. OOM Kill: Falta de memória
3. Dependência não disponível: Banco, Redis, etc.

# Sincronização

# Erro: "Drift detected"

Warning: Drift detected in mysql_meu_banco

Causa: Container foi modificado manualmente ou está diferente da definition.

Solução:

# Ver diferenças
deployally sync --check

# Corrigir (recria container conforme definition)
deployally sync --fix

# Erro: "Container not found"

Error: Container mysql_meu_banco not found but definition exists

Causa: Container foi removido manualmente.

Solução:

# Recriar container
deployally sync --fix

# Ou remover a definition
deployally definitions delete mysql_meu_banco

# Performance

# Deploy lento

Causas possíveis:

1. Download de imagem: Primeira vez é mais lento

   docker pull mysql:8.4  # Pré-baixar imagem

2. Rede lenta: Verifique conexão

3. Disco cheio: Libere espaço

   df -h
   docker system prune  # Limpar dados não usados

# Alto uso de recursos

# Ver uso por container
docker stats

# Ajustar resources na definition
deployally definitions update {nome} --profile minimal

# Logs e Debug

# Habilitar logs verbose

DEPLOYALLY_LOG_LEVEL=debug deployally deploy --species mysql

# Verificar configuração

cat ~/.config/deployally/config.toml

# Testar conectividade

# API
curl -v https://sys.deployally.com/api/v1/health

# Docker
docker info

# Suporte

Se o problema persistir:

1. Colete logs: deployally logs --export
2. Verifique FAQ
3. Entre em contato: suporte@deployally.com