Pular para o conteúdo

Deployment

Fazendo deploy do Rebase no InstaPods

O InstaPods executa seu aplicativo em um container persistente — um pod — com Node.js, um serviço PostgreSQL opcional em localhost, HTTPS automático e deploys a partir de um repositório GitHub. Um backend Rebase é um único processo Node e um Postgres, portanto tudo cabe em um único pod: a API, autenticação, realtime, cron, o painel de administração e o armazenamento de arquivos.

Esta página leva um projeto recém-criado com rebase init para uma URL ativa. Tudo roda no próprio pod; não há imagem Docker nem nada mais para provisionar.

O upload de arquivos pode começar no próprio disco do pod. O sistema de arquivos de um pod sobrevive a reinicializações e novos deploys, portanto o armazenamento local é seguro nele, e você pode migrar para um bucket compatível com S3 mais tarde sem alterar o código. Consulte Armazenamento de arquivos.

  • O plano Build ou superior (US$ 7/mês: 2 vCPUs, 2 GB de RAM, 25 GB de disco). O plano Launch não pode executar o serviço PostgreSQL.
  • Um repositório no GitHub para o projeto.
  • A CLI do InstaPods, para as etapas de banco de dados e ambiente. O painel (dashboard) faz as mesmas coisas.
pnpm dlx @rebasepro/cli init my-app
cd my-app

Faça o commit e envie para um repositório GitHub. O .env está no gitignore e deve continuar assim: o pod recebe seus próprios valores no passo 4.

No painel do InstaPods, crie um pod com o preset Node.js no plano Build.

O scaffold declara Node >=22.22.0 e se recusa a instalar em versões mais antigas. Verifique a versão do pod e atualize-o para o Node 24 se o Node 22 estiver desatualizado:

instapods exec my-app -- node -v
instapods pods node-version my-app 24 --wait
instapods services add my-app -s postgresql -w
instapods services creds my-app -s postgresql

O segundo comando exibe as credenciais: host localhost, porta 5432, usuário e banco de dados instapod, e uma senha gerada. Sua string de conexão é:

postgresql://instapod:<password>@localhost:5432/instapod

Em seguida, crie a role na qual o Rebase executa as requisições autenticadas. O Rebase impõe a segurança em nível de linha (row-level security) alternando cada requisição para uma role restrita, rebase_user, e o usuário instapod precisa de permissão para alternar para ela. Crie-a uma única vez como superusuário do Postgres, antes do primeiro deploy:

instapods ssh my-app
sudo -u postgres psql -d instapod -c "CREATE ROLE rebase_user NOLOGIN NOSUPERUSER NOBYPASSRLS NOINHERIT;" -c "GRANT rebase_user TO instapod;"
exit

O runtime cuida do restante na primeira inicialização: as permissões (grants) e políticas em suas tabelas pertencem ao instapod, que é o proprietário do seu banco de dados.

Faça isso mesmo que o runtime pudesse criar a role por conta própria. No PostgreSQL 16 e mais recentes, um usuário que tem permissão para criar roles, mas não é um superusuário, obtém uma associação na role criada que não permite alternar para ela. A inicialização é bem-sucedida, mas toda requisição autenticada falha com DB_PERMISSION_DENIED. Se isso já aconteceu, execute GRANT rebase_user TO instapod WITH SET TRUE; da mesma forma e reinicie o aplicativo.

Gere os dois segredos com openssl rand -hex 32 (uma vez para cada), e configure tudo em uma única chamada:

instapods env set my-app \
DATABASE_URL='postgresql://instapod:<password>@localhost:5432/instapod' \
ALLOW_LOCALHOST_IN_PRODUCTION=true \
JWT_SECRET=<first-secret> \
REBASE_SERVICE_KEY=<second-secret> \
CORS_ORIGINS=https://my-app.nbg1-1.instapods.app \
FRONTEND_URL=https://my-app.nbg1-1.instapods.app \
DISABLE_SELF_REGISTRATION=true \
REBASE_ADMIN_EMAIL=you@example.com \
REBASE_ADMIN_PASSWORD=<at-least-12-characters> \
STORAGE_TYPE=local \
STORAGE_PATH=/home/instapod/app/uploads \
FORCE_LOCAL_STORAGE=true

Use a própria URL do seu pod para CORS_ORIGINS e FRONTEND_URL: o painel a exibe, e esse é o endereço no qual você abrirá o painel de administração. Adicione um domínio personalizado mais tarde e configure-o em ambos.

Para que servem as linhas menos óbvias:

  • ALLOW_LOCALHOST_IN_PRODUCTION=true. Em produção, o runtime recusa uma DATABASE_URL que aponte para localhost, pois dentro de um container esse endereço geralmente é um engano. Em um pod, o banco de dados realmente fica na mesma máquina, e esta linha confirma isso.
  • REBASE_ADMIN_EMAIL e REBASE_ADMIN_PASSWORD. Em produção, a primeira conta a se registrar não é tornada administradora, então essas variáveis definem o primeiro admin. O runtime cria a conta uma vez, enquanto a tabela de usuários estiver vazia. Faça login com ela e altere a senha. Consulte Seu primeiro admin.
  • As três linhas de storage. Explicadas em Armazenamento de arquivos.

O comando instapods env set grava em /home/instapod/app/.env, que é o arquivo lido pelo rebase start. O próprio InstaPods define a variável PORT, e o runtime se vincula a ela.

Na aba Git do pod, conecte o repositório e a branch, e configure os comandos:

Campo Valor
Install npx -y pnpm@11 install --frozen-lockfile --prod=false
Build npx -y pnpm@11 run build
Release (deixe em branco)
Start env NODE_ENV=production node_modules/.bin/rebase start

Por que cada um é configurado desta forma:

  • Install executa o pnpm via npx, pois o projeto inclui um pnpm-lock.yaml e o pod pode não ter o pnpm instalado. --prod=false mantém as dependências de desenvolvimento — a CLI do Rebase e o TypeScript, necessários para o build —, mesmo se NODE_ENV já estiver definido como production durante a instalação.
  • Build executa rebase build. Ele compila suas tabelas, funções e crons no diretório dist-bundle/, e compila o painel de administração no mesmo bundle. Ele atinge um pico de cerca de 1 GB de memória.
  • Start executa o bundle compilado. NODE_ENV=production é definido no próprio comando, garantindo que o runtime nunca inicialize em modo de desenvolvimento — onde a primeira pessoa desconhecida a se cadastrar se tornaria o administrador.

Faça o deploy. Cada push posterior para a branch realizará um novo deploy.

Abra a URL do pod. Um único processo serve o painel de administração em / e a API em /api. Faça login com REBASE_ADMIN_EMAIL e REBASE_ADMIN_PASSWORD.

A primeira inicialização cria todas as tabelas necessárias, incluindo as suas, juntamente com suas políticas de segurança em nível de linha. Não há migração para executar antes.

Se o log indicar Failed to create the "rebase_user" role, a etapa ao final de Adicione o PostgreSQL foi ignorada: execute-a e, em seguida, instapods pods restart my-app.

Os uploads são armazenados no disco do pod em /home/instapod/app/uploads, um diretório que o .gitignore do scaffold já exclui do repositório.

Em produção, o runtime recusa o armazenamento local a menos que você informe que o disco é permanente, porque na maioria das plataformas de container ele não é: o sistema de arquivos é substituído a cada deploy, e todo arquivo enviado é perdido. Um pod é diferente, pois seus arquivos persistem entre reinicializações e deploys. FORCE_LOCAL_STORAGE=true comunica isso ao runtime.

Manter o diretório dentro de /home/instapod/app também o inclui no backup diário que o InstaPods faz do pod, cobrindo esse diretório e gerando um dump do banco de dados juntamente com ele.

O que o armazenamento local não faz:

  • Servir a partir de mais de uma máquina. Os arquivos existem apenas neste pod. Uma segunda instância, ou uma CDN na frente dos arquivos, precisa de um bucket.
  • Crescer além do disco do plano. Os uploads compartilham os 25 GB com o banco de dados e o aplicativo.

Quando você ultrapassar essa capacidade, conecte qualquer bucket compatível com S3 e remova as três linhas de configuração local:

instapods env unset my-app STORAGE_PATH FORCE_LOCAL_STORAGE
instapods env set my-app STORAGE_TYPE=s3 S3_BUCKET=my-uploads S3_REGION=... \
S3_ENDPOINT=https://... S3_ACCESS_KEY_ID=... S3_SECRET_ACCESS_KEY=...

Arquivos já existentes no pod não são movidos sozinhos: copie-os para o bucket, mantendo suas chaves. Quem pode ler, gravar e listar arquivos é determinado por storageAuthorize em backend/storage.ts, independentemente de qual backend os armazene. Consulte Armazenamento.

O runtime cria as tabelas ausentes na inicialização, incluindo aquelas declaradas em backend/schema. O valor padrão de REBASE_MIGRATE_ON_BOOT é ensure, que é aditivo em todo o schema. Ele cria tabelas, colunas e tipos enum ausentes e aplica a segurança em nível de linha a eles, de modo que uma nova tabela já entra em produção no próximo deploy.

O ensure nunca altera algo que já existe. Ele não modifica o tipo de uma coluna, não remove nada e nem edita os rótulos de um enum existente, pois um deploy não deve remodelar um schema como efeito colateral.

Qualquer alteração que não seja puramente aditiva — uma coluna renomeada, um tipo restringido, um campo removido — requer o rebase db push, executado a partir da sua máquina.

O db push planeja cada alteração em uma cópia temporária do schema, em um banco de dados com o mesmo nome do seu acrescido de _dev_diff no final, e o usuário instapod não tem permissão para criar bancos de dados. Crie-o uma única vez como superusuário:

instapods ssh my-app
sudo -u postgres psql -c "CREATE DATABASE instapod_dev_diff OWNER instapod;"
exit

O Postgres do pod escuta apenas em localhost, portanto acesse-o por meio de um túnel SSH e, em seguida, faça o push:

ssh -N -L 5433:localhost:5432 instapod@<pod-host> -p <ssh-port>
pnpm exec rebase db push --dry-run --database-url 'postgresql://instapod:<password>@localhost:5433/instapod'

Leia o SQL exibido pelo dry run e execute novamente sem --dry-run. Uma alteração que remova dados também exigirá --allow-destructive.

Para migrações versionadas, faça commit dos arquivos de migração gerados com rebase db generate e coloque node_modules/.bin/rebase db migrate no campo Release, que o InstaPods executa a cada deploy.

Se suas tabelas declararem uma coluna col.vector(), o Postgres do pod precisará da extensão pgvector: instalada no pod e depois criada pelo superusuário com sudo -u postgres psql -d instapod -c "CREATE EXTENSION vector;". O scaffold não declara nenhuma.

  • Deployment — o checklist de produção e as regras do primeiro admin compartilhadas por todas as plataformas.
  • Configuração — todas as variáveis de ambiente lidas pelo runtime.
  • Armazenamento — buckets, regras de acesso e várias fontes de armazenamento simultâneas.