Como atualizar uma aplicação Bun na VPS sem perder a versão anterior

Fala aí, beleza? Rodar um bun upgrade direto em produção parece inofensivo, até a aplicação começar a se comportar diferente e você não lembrar qual versão estava rodando antes 😛

Este guia serve para quem roda uma aplicação Bun numa VPS com acesso root, seja direto no servidor ou dentro de Docker

A ideia é simples: cada atualização precisa ter um caminho de volta conhecido ANTES de você apertar o enter

O que você precisa antes de atualizar o Bun na VPS

Você precisa de uma VPS com acesso root, porque vai instalar binários do Bun e, se for o caso, rodar Docker

Aqui 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. Segundo a página oficial da VPS, os planos KVM 1, KVM 2, KVM 4 e KVM 8 oferecem acesso root, processadores AMD EPYC e armazenamento NVMe SSD. Na página específica da VPS no Brasil, a Hostinger detalha esse acesso como root completo (full root access)

E o que isso tem a ver com este tutorial?

• Root completo: é o que deixa você instalar e trocar versões do Bun sem pedir permissão pra ninguém
• Backups automáticos semanais e snapshots manuais: são o seu ponto de volta se algo sair do controle
• Servidor no Brasil: a Hostinger tem VPS com localização no Brasil, útil se o seu público está aqui

Do lado do projeto, o item mais importante é o lockfile

O bun.lock precisa estar commitado no controle de versão. Ele é o que o bun install --frozen-lockfile (ou bun ci) usa pra instalar exatamente as mesmas versões que você testou. Se o package.json estiver em desacordo com o bun.lock, a instalação falha em vez de resolver dependências diferentes: e é esse o comportamento que você quer no deploy

Tome cuidado com projeto antigo! Desde o Bun 1.2, o lockfile padrão é o bun.lock em texto. Antes disso era o bun.lockb, binário

Se o seu projeto ainda tem o bun.lockb, converta assim:

bun install --save-text-lockfile --frozen-lockfile --lockfile-only

Depois apague o bun.lockb e commite o bun.lock novo

Se a aplicação roda em Docker, o Dockerfile deve partir da oven/bun, que, segundo o guia da Docker para Bun, é a Docker Official Image do Bun, criada pela Oven (a empresa por trás do Bun) e disponível no Docker Hub

Como atualizar o runtime do Bun com a versão anterior à mão

Primeiro um conceito rápido: o que é o runtime aqui?

É o próprio executável do Bun. Segundo a documentação de instalação, ele é distribuído como um único executável, sem dependências

Isso é ótimo pra rollback, porque trocar de versão é basicamente trocar esse binário 🙂

1. Crie um snapshot antes de mexer em qualquer coisa

No painel da Hostinger: VPS → Manage → Backups & Monitoring → Snapshots & Backups → Create Snapshot

Se liga no limite: segundo o suporte da Hostinger, só um snapshot fica guardado por vez, o novo sobrescreve o anterior, e ele é apagado automaticamente depois de 1 dia

Erro comum deste passo: criar outro snapshot logo depois da atualização, "só por garantia". Se a versão nova estiver com problema, você acabou de sobrescrever o único ponto bom

2. Anote a versão atual e o commit exato do binário

   bun --version
   bun --revision

O --version mostra a versão, o --revision mostra o commit exato do binário que está rodando

Erro comum deste passo: pular a anotação. Aí a atualização quebra e você não sabe para qual versão voltar… já vi muita gente presa exatamente aqui

3. Atualize de forma deliberada

O caminho rápido é este:

   bun upgrade

Segundo o guia de upgrade, ele baixa e instala a versão estável mais recente e substitui a que está instalada

Funciona, mas você não escolhe o destino. Em produção, prefira rodar o script oficial passando a tag da versão (formato bun-vX.Y.Z):

   curl -fsSL https://bun.sh/install | bash -s "bun-vX.Y.Z"

Troque X.Y.Z pela versão que você quer. E o melhor: o MESMO comando serve pra reinstalar uma versão anterior: o exemplo atual da documentação usa a tag "bun-v1.3.3", mas troque pelo número que você precisa

Erro comum deste passo: usar bun upgrade --canary no servidor. A documentação não recomenda builds canary para produção. Se você já caiu numa, volte para a última estável com bun upgrade --stable

4. Confira de novo

   bun --version
   bun --revision

Resultado esperado: a versão que você escolheu, não outra. Se apareceu algo diferente, pare aqui antes de reiniciar a aplicação

Como atualizar a aplicação Bun sem mudar as dependências por acidente

Atualizar o runtime é uma coisa, atualizar a aplicação é outra

Na aplicação, o risco é o servidor resolver dependências diferentes das que você testou na sua máquina. O lockfile congelado resolve isso

1. Instale as dependências com lockfile congelado

   bun install --frozen-lockfile

Ou, se preferir, use bun ci: a documentação do bun install trata os dois no mesmo contexto de lockfile congelado. Esse comportamento instala exatamente as versões que estão no bun.lock, não atualiza o lockfile, e sai com erro se o package.json estiver em desacordo com ele

Falhar parece ruim, né? Mas aqui é exatamente o que você quer: o deploy para em vez de subir dependências que ninguém testou

2. Opcional: deixe o congelamento fixo no bunfig.toml

Na seção install do bunfig.toml, coloque:

   frozenLockfile = true

Assim um bun install esquecido no servidor também não destrava nada

Erro comum deste passo: editar o package.json direto no servidor sem regenerar e commitar o bun.lock. O install congelado vai falhar, e com razão

Como verificar: o install termina sem erro e o bun.lock continua igual ao que está no repositório

Como atualizar uma aplicação Bun em Docker mantendo a imagem anterior

No Docker, a versão anterior é a imagem anterior. O truque é não apagar ela sem querer

Se você ainda está montando esse ambiente, comece revisando a imagem base e o Dockerfile antes de pensar em atualização. Aqui o foco é a atualização, seguindo o guia oficial de Docker do Bun

1. Escolha uma tag de imagem base mais específica que latest

Use oven/bun:1 como tag principal. Se quiser uma imagem menor, o Bun também publica as variantes oven/bun:debian, oven/bun:slim, oven/bun:distroless e oven/bun:alpine (a imagem suporta Linux x64 e arm64)

Vale notar: o Dockerfile de exemplo do guia oficial de Docker para Bun usa oven/bun:latest. Pra produção, a recomendação da Hora de Codar é diferente: use oven/bun:1 em vez de latest. Ela ainda é uma tag flutuante, dentro da linha 1.x ela pode receber builds novos do Bun, mas reduz a chance de um salto de versão major inesperado que o latest permitiria. Combine isso com o --pull deliberado e um nome de imagem por versão (próximos passos) pra decidir você mesmo quando aceitar um binário novo do Bun

2. Instale as dependências com lockfile congelado e sem devDependencies

Trecho didático do Dockerfile (a cópia dos arquivos do projeto segue o guia oficial):

   FROM oven/bun:1
   # ... cópia dos arquivos do projeto, como no guia oficial
   RUN bun install --frozen-lockfile --production

O --frozen-lockfile faz o mesmo papel do bun ci e o --production deixa as devDependencies de fora

3. Gere a imagem nova com um nome diferente a cada versão

   docker build --pull -t minha-app-v2 .

O -t dá nome à imagem. O --pull força o Docker a buscar uma versão mais nova da imagem base mesmo que já exista uma cópia em cache local

É por isso que uma mesma tag como oven/bun:1 pode acabar apontando para um build diferente do Bun ao longo do tempo: use o --pull de forma deliberada, só quando quiser testar essa imagem base mais recente antes de subir pra produção. Pra manter o controle, anote a versão do Bun que entrou em cada build junto do nome da imagem

Erro comum deste passo: usar sempre o mesmo nome no -t. Você sobrescreve a única cópia da versão que funcionava e fica sem imagem pra voltar

A atualização quebrou a aplicação: como voltar para a versão anterior

Vai pelo sintoma, do mais simples ao mais drástico:

• Comportamento estranho depois de bun upgrade: a causa provável é a mudança de runtime. Reinstale a versão que você anotou com curl -fsSL https://bun.sh/install | bash -s "bun-vX.Y.Z" e confira com bun --version e bun --revision
• Erros vindos de uma build canary: rode bun upgrade --stable para voltar à última estável
• Install falhando por causa do lockfile: o bun.lock e o package.json estão dessincronizados. Corrija no repositório e commite, não destrave o lockfile no servidor
• Imagem Docker nova com problema: volte para a imagem anterior, que continua disponível se você usou outro nome no -t
• Nada disso resolveu: restaure o snapshot

Tome cuidado com o último item!

Restaurar um snapshot ou backup sobrescreve TODO o conteúdo atual da VPS. Depois de iniciada, a restauração não pode ser parada, cancelada nem revertida, e a VPS fica bloqueada durante o processo

O andamento aparece em Backups & Monitoring → Latest actions, na entrada backup_restore

Como prevenir

• Anote bun --version e bun --revision antes de cada atualização
• Faça todo deploy com bun install --frozen-lockfile (ou bun ci) ou com frozenLockfile = true no bunfig.toml
• No Docker, mantenha a tag base específica e use um nome de imagem por versão
• Crie o snapshot imediatamente antes de atualizar, nunca depois

Vídeo: atualizando Node e NPM

A lógica de saber qual versão está rodando antes de trocar vale pra qualquer runtime JavaScript

No vídeo abaixo, o assunto é como atualizar o Node e o NPM para a versão mais recente, passo a passo 😀

Próximo passo

Escolha a versão exata do Bun que vai para produção e registre ela junto do projeto: a tag bun-vX.Y.Z do script ou a tag da imagem no Dockerfile

No próximo deploy, rode bun install --frozen-lockfile (ou bun ci) e deixe a versão anterior disponível com outro nome. Se der ruim, você já sabe exatamente pra onde voltar

Ainda não tem servidor? Dá pra conferir a VPS para este projeto, com o root completo e os snapshots manuais que este tutorial usa

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.