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 que você precisa
Seção intitulada “O que você precisa”- 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.
1. Crie o projeto e faça o push
Seção intitulada “1. Crie o projeto e faça o push”pnpm dlx @rebasepro/cli init my-appcd my-appFaç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.
2. Crie o pod
Seção intitulada “2. Crie o pod”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 -vinstapods pods node-version my-app 24 --wait3. Adicione o PostgreSQL
Seção intitulada “3. Adicione o PostgreSQL”instapods services add my-app -s postgresql -winstapods services creds my-app -s postgresqlO 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/instapodEm 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-appsudo -u postgres psql -d instapod -c "CREATE ROLE rebase_user NOLOGIN NOSUPERUSER NOBYPASSRLS NOINHERIT;" -c "GRANT rebase_user TO instapod;"exitO 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.
4. Configure o ambiente
Seção intitulada “4. Configure o ambiente”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=trueUse 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 umaDATABASE_URLque aponte paralocalhost, 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_EMAILeREBASE_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.
5. Conecte o repositório
Seção intitulada “5. Conecte o repositório”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 umpnpm-lock.yamle o pod pode não ter o pnpm instalado.--prod=falsemantém as dependências de desenvolvimento — a CLI do Rebase e o TypeScript, necessários para o build —, mesmo seNODE_ENVjá estiver definido comoproductiondurante a instalação. - Build executa
rebase build. Ele compila suas tabelas, funções e crons no diretóriodist-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.
6. Acesse o aplicativo
Seção intitulada “6. Acesse o aplicativo”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.
Armazenamento de arquivos
Seção intitulada “Armazenamento de arquivos”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_STORAGEinstapods 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 schema
Seção intitulada “O schema”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-appsudo -u postgres psql -c "CREATE DATABASE instapod_dev_diff OWNER instapod;"exitO 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.
Próximos passos
Seção intitulada “Próximos passos”- 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.