Como restaurar o Coolify em outra VPS sem perder configurações e segredos

Fala aí, beleza? Trocar o Coolify de máquina dá um frio na barriga, porque ali dentro estão projetos, credenciais e o histórico de deploys de tudo que você publicou 😅

Este guia cobre só esse cenário: a instância antiga existe (ou existiu), e você quer subir tudo numa VPS separada sem reconfigurar nada na mão. Vale só para instâncias self-hosted: se a sua instância é do Coolify Cloud, a recuperação fica com a equipe do Coolify

O checklist de backup de rotina fica de fora, beleza? Aqui o foco é a recuperação na máquina nova, os segredos que precisam bater e a reconexão dos servidores gerenciados

O que você precisa antes de restaurar o Coolify

Antes de tudo, se liga no porquê: a restauração substitui o banco da instalação nova pelo do backup e traz de volta projetos, recursos, configurações, credenciais salvas e histórico de deploys, segundo a documentação de restauração da instância

Mas ela NÃO traz os dados guardados dentro das suas aplicações, dos bancos de dados, dos serviços ou dos volumes: isso precisa vir dos backups de cada recurso, não do backup da instância

Só que as credenciais dentro desse banco estão criptografadas

E quem abre esse cofre é o APP_KEY

Sem o MESMO APP_KEY usado quando o backup foi criado, o Coolify não consegue ler as credenciais nem as chaves privadas do banco restaurado. A documentação é direta nesse ponto: se o arquivo de backup e o APP_KEY salvo não forem da instância que você quer recuperar, não siga em frente: o comando de restauração remove os objetos atuais do banco antes de carregar o backup

Da instância de origem:

• O arquivo de backup do banco, com extensão .dmp
• O valor do APP_KEY
• Acesso SSH ao servidor
• A pasta /data/coolify/ssh/keys/ e o arquivo ~/.ssh/authorized_keys (ou um backup separado deles)
• Se você salvou, o número da versão que aparecia no painel quando o backup foi criado: ele é útil mais adiante, ao reinstalar o Coolify

Tome cuidado com um detalhe: o APP_KEY fica em /data/coolify/source/.env, e esse arquivo NÃO vem dentro do backup do banco, conforme a página de backup da instância. Os backups no S3 incluem só o arquivo do banco, por isso a chave precisa ser salva à parte

Da VPS de destino:

• Linux, em arquitetura amd64 ou arm64 (Debian/Ubuntu, Red Hat, SUSE, Arch, Alpine ou Raspberry Pi OS 64 bits)
• No mínimo 2 núcleos de CPU, 2 GB de RAM e 10 GB de disco livre
• Acesso root, que o script de instalação exige

Esses requisitos estão no guia oficial de self-hosted

Qual VPS usar como destino?

A recomendação principal da Hora de Codar pra esse projeto é a VPS da Hostinger (este artigo contém links de afiliado da Hostinger)

O motivo é bem ligado à tarefa: a VPS dá acesso root, que o instalador do Coolify pede, roda em processadores AMD EPYC com armazenamento SSD NVMe, tem backups semanais automáticos grátis e permite restaurar a VPS pelo próprio painel de controle, segundo a página de VPS da Hostinger

As especificações dos planos KVM listadas na página de hospedagem para Coolify:

Plano	vCPU	RAM	Armazenamento NVMe
KVM 2	2	8 GB	100 GB
KVM 4	4	16 GB	200 GB
KVM 8	8	32 GB	400 GB

Os três passam do mínimo de 2 núcleos, 2 GB de RAM e 10 GB de disco pedido pelo Coolify 🙂

A Hostinger também oferece um plano com o Coolify pré-instalado (template Ubuntu 24.04 com Coolify), com acesso root completo. Se você for restaurar um backup antigo sobre esse template, vale conferir a versão do Coolify que vem instalada antes de carregar o dump: se você salvou o número da versão da origem (seção acima), compare os dois antes de seguir

Passo a passo para migrar o Coolify para outra VPS

Bora ver na prática? A ordem importa, principalmente em três pontos que o checklist de backup comum não cobre: parar o control plane antes do restore, trocar o APP_KEY ANTES (não depois) do pg_restore, e subir o Coolify de novo no final pra aplicar as migrações do banco

1. Salve o APP_KEY na origem

No servidor antigo, rode:

grep '^APP_KEY=' /data/coolify/source/.env

O terminal mostra a linha do APP_KEY

Copie a linha INTEIRA pra um gerenciador de senhas ou outro local seguro fora do servidor do Coolify

Erro comum deste passo: achar que o backup do banco já leva o .env junto. Não leva!

2. Gere e baixe o backup do banco

No painel, vá em Settings, aba Backup. Em Backup schedule, selecione "Back up now". Na primeira vez, o Coolify pede pra você selecionar "Configure backup", o que liga um backup diário

Quando a execução terminar (o status vai de In Progress para Success), clique em "Download" pra salvar uma cópia no seu computador, enquanto o Local Storage estiver disponível

Se você usa backup automático em armazenamento compatível com S3, saiba que o painel não baixa um arquivo que está só no remoto: nesse caso, baixe pelo provedor de S3 e copie o arquivo pro servidor que vai fazer a restauração

3. Copie as chaves SSH da origem

O Coolify guarda as chaves dos servidores gerenciados em /data/coolify/ssh/keys/

Leve essa pasta e o ~/.ssh/authorized_keys da origem pra um local seguro fora do servidor

Sem eles, a instância nova sobe mas não consegue falar com os servidores que gerenciava

4. Instale o Coolify na VPS nova

Com acesso root (ou um usuário com privilégios sudo), rode o instalador oficial:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

A instalação automática por script exige acesso de usuário root: a documentação orienta conectar via SSH como root ou como usuário com privilégios sudo

Essa instalação sobe a versão estável mais recente do Coolify, já que o comando acima não fixa nenhum número de versão. Guarde esse detalhe: é ele (a versão que ficou instalada agora, neste passo), e não o número de versão da instância de ORIGEM, que vai importar lá no passo 9, quando o Coolify for reinstalado depois do restore

5. Pare o control plane antes de restaurar

Antes de tocar no banco, pare os containers do painel:

docker stop coolify coolify-redis

O coolify-db precisa continuar rodando, porque é nele que o próximo passo vai escrever. Em versões anteriores à migração para o Reverb, pare também o coolify-realtime

O painel fica fora do ar durante a restauração, mas os recursos já publicados e o Coolify Proxy continuam rodando normalmente

6. Troque só o valor do APP_KEY no .env novo

Abra o .env do Coolify no servidor novo (sudo nano /data/coolify/source/.env), ache a linha APP_KEY= e substitua só o valor pelo que você salvou no passo 1

O resto do arquivo fica como está

Erro comum deste passo: copiar o .env inteiro da origem por cima do novo. Valores como o DB_PASSWORD pertencem à instalação nova e precisam continuar batendo com os containers em execução

7. Restaure o dump no container do banco

Envie o arquivo .dmp pra VPS nova e confira se ele chegou inteiro antes de restaurar:

export BACKUP_PATH=/data/backups/coolify-db-backup.dmp
test -s "$BACKUP_PATH" && ls -lh "$BACKUP_PATH"

Troque o caminho se o seu arquivo estiver em outro lugar. Com o coolify-db como único container usando o banco, rode:

docker exec -i coolify-db pg_restore --clean --if-exists --exit-on-error --no-acl --no-owner --username=coolify --dbname=coolify < "$BACKUP_PATH"

Esse comando substitui o banco da instalação nova pelo conteúdo do backup. Como ele usa --exit-on-error, a restauração para no primeiro erro em vez de seguir pela metade

8. Recoloque as chaves SSH antigas

A documentação do Coolify tem uma aba específica pra cenário de "servidor substituto" (replacement server), com as instruções de como recolocar os arquivos de /data/coolify/ssh/keys/ e o authorized_keys que você guardou no passo 3

Como mexer nessas chaves pode travar o acesso do Coolify aos servidores gerenciados (ou sobrescrever acesso SSH de forma destrutiva se feito errado), siga as instruções dessa aba específica na documentação de restauração da instância antes de copiar ou substituir qualquer arquivo dessa pasta no servidor novo

9. Suba o Coolify de novo

Com os containers do control plane parados desde o passo 5, rode o instalador outra vez. A documentação pede pra usar aqui a MESMA versão que ficou instalada depois do passo 4, antes de restaurar o banco. Como o passo 4 deste guia instalou a versão estável mais recente (sem fixar nenhum número), omita o -s nesta reinstalação também:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

Se no seu caso o passo 4 tiver fixado uma versão específica com -s <versão>, use essa MESMA versão aqui, assim: sudo bash -s <versão>. O número de versão da instância de ORIGEM é um dado diferente: ele serve só pra comparação se você for restaurar sobre uma VPS que já vem com o Coolify pré-instalado, como a hospedagem Coolify da Hostinger mencionada antes

Esse comando sobe de novo os containers do Coolify e aplica as migrações de banco necessárias. Espere a instalação terminar antes de abrir o painel

Credenciais ilegíveis ou servidor inacessível depois da restauração

A restauração está confirmada quando o painel abre sem erro de criptografia, os projetos e ambientes aparecem, o servidor localhost valida com sucesso em Servers, os outros servidores gerenciados conectam e os deploys recentes aparecem como esperado

Se algo não bateu, quase sempre cai num destes dois casos:

Por que as credenciais não podem ser lidas?

Sintoma: o painel mostra um erro de criptografia (algo como "encryption" ou "Invalid MAC")

Causa provável: o APP_KEY da instância nova é diferente do usado quando o backup foi criado

Solução: refaça o passo 6 com o APP_KEY salvo da origem

Por que os servidores gerenciados ficaram inacessíveis?

Sintoma: o Coolify não alcança os servidores que gerenciava antes

Causa: as chaves de /data/coolify/ssh/keys/ ou o authorized_keys não foram migrados corretamente

Solução: em Servers > servidor > Private Key, clique em "Check connection". Se não vier como reachable, confira se a chave pública está mesmo no ~/.ssh/authorized_keys do usuário SSH configurado e refaça o passo 8 seguindo a aba de servidor substituto na documentação

Como evitar esses problemas na próxima migração?

Guarde o APP_KEY, as chaves SSH e os backups da instância fora do servidor, sempre: são o material de recuperação mais sensível que o Coolify produz

Mantenha os backups semanais da Hostinger ativos na VPS e, se fizer mudanças grandes antes de uma restauração, confira na própria central de ajuda da Hostinger como funciona a restauração da VPS pelo painel pra essa máquina específica

E se tu curte acompanhar novidades de IA, se liga neste episódio do Matheus Battisti Show 😀

Próximo passo depois da migração

Agora que a instância nova está de pé, ela tem as próprias chaves e o próprio .env

O próximo backup vai depender delas, então rode o grep do passo 1 nesse servidor novo e guarde o APP_KEY e as chaves SSH fora dele hoje mesmo

Se o servidor de destino ainda não existe, vale começar pelo guia de instalar o Coolify na VPS e voltar aqui depois

E se você ainda precisa da máquina nova, dá pra conferir a VPS para este projeto e escolher o plano KVM que cabe nas suas aplicações

Até o próximo post! 🙂

Perguntas frequentes

Restaurar o backup do Coolify traz de volta os dados das minhas aplicações?

Não. A restauração do Coolify traz de volta projetos, recursos, configurações, credenciais salvas e histórico de deploys, mas não traz os dados guardados dentro das aplicações, dos bancos de dados, dos serviços ou dos volumes. Esses dados precisam ser restaurados a partir dos backups de cada recurso, separadamente.

Por que o APP_KEY precisa ser o mesmo da instância de origem?

O APP_KEY é a chave que criptografa as credenciais e as chaves privadas salvas no banco do Coolify. Sem o mesmo APP_KEY usado quando o backup foi criado, o painel não consegue ler esses dados depois da restauração e mostra um erro de criptografia.

Como saber se a migração do Coolify para a nova VPS deu certo?

O painel precisa abrir sem erro de criptografia, com os projetos, ambientes e recursos aparecendo normalmente. Em Servers, o servidor localhost precisa validar com sucesso, os outros servidores gerenciados precisam conectar, e os deploys recentes e as configurações da instância precisam aparecer como esperado.

Esse guia funciona para o Coolify Cloud?

Não. Este procedimento vale só para instâncias self-hosted. Se a sua instância é do Coolify Cloud, a recuperação de backup é feita pela própria equipe do Coolify.

Quer aprender mais sobre inteligência artificial e programação na prática? Conheça o canal Hora de Codar no YouTube e acompanhe os próximos vídeos.