Como migrar uma API FastAPI para outra VPS sem perder configuração e dados

Fala aí, beleza? Migrar FastAPI para outra VPS é levar quatro coisas separadas: a imagem (o Dockerfile e o código), a configuração (variáveis de ambiente e proxy), os dados (volume do Docker ou dump do PostgreSQL) e o apontamento de DNS

A ordem que evita dor de cabeça: baixar o TTL com antecedência, subir o servidor novo, restaurar os dados, validar pelo IP e só então trocar os registros A, com o servidor antigo ligado como plano de retorno

Aqui o foco é a mudança de casa, não o primeiro deploy com Docker e HTTPS

Se a API ainda nem está no ar, começa por lá e depois volta aqui 🙂

O que você precisa antes de migrar a API FastAPI

Antes de encostar em qualquer coisa, confere se você tem:

• Acesso root via SSH ao servidor antigo e ao novo
• Docker instalado no destino
• Acesso à Zona DNS do domínio
• Espaço em disco nos dois lados para guardar os backups

Pra ser o destino, a recomendação principal da Hora de Codar é a VPS da Hostinger (este artigo contém links de afiliado da Hostinger)

O motivo é técnico e casa com a tarefa: todos os planos de VPS dela têm acesso root, armazenamento SSD NVMe, processadores AMD EPYC e backups semanais automáticos gratuitos

Tem também servidores no Brasil, o que ajuda se a sua API atende público daqui

E uma mão na roda pra migração: segundo a central de ajuda da Hostinger, existe um template com Ubuntu 24.04, docker-ce e docker-compose já instalados pra usar na nova VPS

Ou seja, nada de ficar instalando Docker na mão no servidor novo

Pra dimensionar, use como referência as configurações dos planos KVM:

• KVM 1: 1 vCPU, 4 GB de RAM e 50 GB NVMe
• KVM 2: 2 vCPU, 8 GB de RAM e 100 GB NVMe

O topo da linha chega a 8 vCPU, 32 GB de RAM e 400 GB de armazenamento

A regra prática é olhar o consumo atual da sua API e do banco no servidor antigo e escolher um plano que comporte isso com folga, contando também o espaço dos dumps

Passo a passo para migrar FastAPI para outra VPS

Cada passo abaixo tem a ação, um exemplo apoiado em documentação oficial, o que você deve ver no final e o erro que mais derruba gente

1. Faça o inventário do servidor antigo:

Por que começar aqui? Porque o que você não anota, você esquece de levar haha

Liste no servidor antigo:

• O Dockerfile e o código da aplicação
• Todas as variáveis de ambiente (credenciais do banco, chaves, URLs)
• Os volumes do Docker e onde cada um é montado
• Qual banco a API usa e em qual contêiner ele roda
• Como o proxy está configurado (Nginx, Traefik ou outro)
• Quantos processos a API sobe, porque isso mexe direto no consumo de memória (vale rever os workers do FastAPI com pouca RAM se o plano novo for menor)

Resultado esperado: uma lista que permite reconstruir o ambiente sem precisar abrir o servidor antigo pra "dar uma olhadinha"

Erro comum: confiar que tudo está no repositório

Variável de ambiente costuma viver só no servidor, e é justamente ela que faz a API não conectar no banco depois da migração

2. Reduza o TTL do DNS com antecedência:

O TTL diz por quanto tempo os resolvedores guardam a resposta do DNS em cache

Se liga nisso: reduzir o TTL não é retroativo

As respostas antigas, com o TTL alto, continuam em cache até expirar, por isso a redução tem que acontecer antes da troca e não na hora (a Cloudflare explica isso nas boas práticas de DNS)

Resultado esperado: quando chegar a hora de trocar o IP, a mudança se espalha mais rápido

Erro comum: baixar o TTL no mesmo minuto em que troca o registro A e achar que resolveu

3. Prepare o destino e reconstrua a imagem:

Na nova VPS, escolha o template Ubuntu com Docker e leve o código e o Dockerfile pra lá

A documentação de Docker do FastAPI recomenda copiar primeiro só o arquivo de dependências e o resto do código depois, pra aproveitar o cache de camadas do Docker

Trecho baseado no exemplo oficial:

COPY ./requirements.txt /code/requirements.txt
RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
COPY ./app /code/app
CMD ["fastapi", "run", "app/main.py", "--port", "80", "--proxy-headers"]

E o que significa esse --proxy-headers?

A documentação oficial do FastAPI recomenda incluir essa opção quando o contêiner roda atrás de um proxy como Nginx ou Traefik

Resultado esperado: a imagem builda na nova VPS e o contêiner sobe com as mesmas variáveis do inventário

Erro comum: esquecer o --proxy-headers quando a API roda atrás de Nginx ou Traefik, já que é a orientação oficial da documentação do FastAPI pra esse cenário

Revise com calma a configuração do proxy nessa etapa, porque é um dos pontos mais sensíveis da migração

4. Exporte os dados do servidor antigo:

Aqui depende de onde os dados moram

Se é PostgreSQL, use o pg_dump no formato custom (-Fc)

Segundo a documentação do pg_dump, o formato custom está entre os formatos de saída mais flexíveis (ao lado do formato directory): permite selecionar e reordenar itens, aceita restauração paralela e já vem comprimido por padrão

E isso ajuda bastante na migração: segundo a mesma documentação, os formatos de arquivo (archive) são portáveis entre arquiteturas

Exemplo didático (troque o nome do banco pelo seu):

pg_dump -Fc -f api.dump nome_do_banco

Se os dados vivem num volume do Docker (uploads, arquivos gerados pela API e por aí vai), vale lembrar o que diz a documentação de volumes do Docker: volumes são mais fáceis de copiar em backup ou migrar do que bind mounts, e por isso são o mecanismo preferido pra persistir dados de contêiner

Na prática, isso costuma ser feito subindo um contêiner temporário que monta o volume de origem, empacota o conteúdo num arquivo .tar e deixa esse arquivo acessível fora do contêiner

Como a sintaxe exata pode variar entre versões do Docker, confere o comando recomendado na documentação oficial de volumes antes de rodar isso em produção, e adapta os nomes de contêiner e caminho de montagem pros que você anotou no inventário

Depois leve o api.dump ou o arquivo .tar pra nova VPS pelo método de transferência que você já usa

Resultado esperado: um arquivo de backup no servidor antigo e uma cópia dele no novo

Erro comum: gerar o dump com a API ainda gravando dados e depois estranhar registro faltando

Se a API recebe escrita o tempo todo, planeje uma janela em que ela pare de gravar antes do dump final

5. Restaure os dados na nova VPS:

Pra PostgreSQL, o dump em formato custom é restaurado com pg_restore:

pg_restore -d nome_do_banco api.dump

Pra volume do Docker, o caminho é o inverso do backup: um contêiner temporário monta o volume novo (o de destino) e extrai o conteúdo do arquivo .tar dentro dele

De novo, confere a sintaxe exata na documentação oficial de volumes do Docker antes de aplicar, porque ela pode mudar conforme a versão

Resultado esperado: o banco e os volumes da nova VPS com o mesmo conteúdo do antigo

Erro comum: restaurar num banco que ainda não foi criado no destino ou com o nome diferente do que está nas variáveis de ambiente

6. Tire um snapshot da nova VPS:

Com tudo restaurado, vale congelar esse estado antes das mudanças finais

No painel da Hostinger, o caminho é VPS > Manage (ao lado do servidor) > Backups & Monitoring > Snapshots & Backups, e o snapshot é criado pelo botão Create Snapshot, conforme a central de ajuda da Hostinger

Tome cuidado com as regras do snapshot:

• É uma cópia manual da VPS inteira, e só cabe um por vez
• Expira depois de 1 dia
• É apagado se você reinstalar o sistema operacional ou restaurar um backup
• Restaurar um snapshot ou backup sobrescreve todo o conteúdo atual, e o processo não pode ser interrompido, cancelado nem revertido

Por isso ele entra aqui, depois do template escolhido e dos dados restaurados: se fosse tirado antes da instalação do sistema, seria apagado na reinstalação

Erro comum: tirar o snapshot e fazer a troca de DNS dias depois, quando ele já expirou

Como validar a API na nova VPS antes de trocar o DNS

A validação é feita pelo IP da nova VPS, com o domínio ainda apontando pro servidor antigo

Assim o tráfego real continua no servidor que funciona enquanto você confere o novo

Cheque três coisas:

1. A API responde pelo IP novo nos endpoints que você já conhece
2. Os dados restaurados aparecem: busca registros que você sabe que existem no servidor antigo e compara
3. A configuração do proxy foi replicada como no inventário, incluindo a flag --proxy-headers recomendada pela documentação do FastAPI pra quem roda atrás de Nginx ou Traefik

Erro comum: olhar só se o contêiner subiu

Contêiner rodando não quer dizer banco com os registros esperados

Já vi muito "tá no ar!" que na verdade era uma API linda conectada num banco vazio xD

Como apontar o domínio para a nova VPS

Validou? Agora sim troca o DNS

Na Zona DNS, apague os registros A existentes de @ e www e crie dois registros A novos (@ e www) com o IP da nova VPS

Segundo a Hostinger, a propagação pode levar até 24 horas

Erro comum: manter um registro A antigo junto do novo

Aí parte das requisições cai num servidor e parte no outro, e os dados começam a se dividir entre os dois bancos

Plano de retorno: o que fazer se a migração der errado

O retorno é simples porque o servidor antigo continua ligado: volte os registros A pro IP antigo e espere a propagação

Antes de chegar nisso, vale identificar o sintoma:

Dados faltando na nova VPS

Causa provável: dump gerado com a API ainda gravando, ou restauração incompleta

Correção: pare a escrita, refaça o pg_dump ou o backup do volume e restaure de novo

Comportamento estranho atrás do proxy (redirecionamento ou URL errada)

Causa provável: a configuração do proxy na nova VPS ficou diferente da registrada no inventário, por exemplo sem a flag --proxy-headers recomendada pela documentação do FastAPI pra quem roda atrás de Nginx ou Traefik

Correção: compare o CMD do Dockerfile com o que estava no servidor antigo, reconstrua a imagem e suba o contêiner de novo

Domínio ainda caindo no servidor antigo

Causa provável: propagação ainda em andamento ou registro A antigo esquecido na zona

Correção: revise os registros A de @ e www e aguarde, lembrando que pode levar até 24 horas

E o snapshot?

Ele serve pra voltar a nova VPS ao estado salvo, mas restaurar sobrescreve tudo e não tem volta

Qualquer dado gravado depois do snapshot some, então não use isso como primeiro reflexo

Pra prevenir:

• Reduza o TTL com antecedência
• Não desligue o servidor antigo antes da validação completa
• Faça a troca de DNS enquanto o snapshot ainda está dentro do prazo

Vídeo do canal

Quer conhecer mais do canal? Se liga nesse vídeo com a configuração completa do OpenClaw com o modelo Pony Alpha 😀

Próximo passo depois da migração

Com o tráfego confirmado na nova VPS, monte a rotina de backup antes de desligar o servidor antigo

Os backups automáticos semanais da Hostinger ajudam a recuperar a VPS em caso de desastre, mas não substituem os dumps do próprio banco, que são os que você restaura de forma seletiva e leva pra qualquer máquina

Combina os dois, e só depois de ver um dump novo sendo gerado no servidor novo é que vale desligar o antigo

Se ainda está escolhendo onde a API vai morar, dá pra conferir a VPS para este projeto e partir do template com Docker

Boa migração e até o próximo post! 😀

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.