Deployment
Deploy di Rebase su Out Plane
Out Plane compila ed esegue applicazioni a partire da un repository GitHub, con PostgreSQL gestito e bucket compatibili con S3 nella stessa console, in Germania. Un backend Rebase è composto da un singolo container e un’istanza Postgres, quindi si mappa su tre risorse di Out Plane: un’app, un database e un bucket.
Questa pagina guida un progetto appena creato con rebase init fino a un URL live, su una singola istanza.
Scritto per Rebase 0.32.0. La versione è fissata nel Dockerfile al passaggio 3; aggiornarla in seguito richiede solo la modifica di quella singola riga.
I caricamenti di file vanno su un bucket fin dal primo giorno. Il filesystem di un’app Out Plane viene ripristinato a ogni nuovo deploy, quindi i file salvati sul suo disco andrebbero persi al push successivo. Consulta Archiviazione file.
Di cosa hai bisogno
Sezione intitolata “Di cosa hai bisogno”- Un account Out Plane. Il piano Starter copre quanto descritto in questa pagina: un’app, un database gestito e un bucket.
- Un repository GitHub per il progetto.
- Facoltativamente, la
outplaneCLI. Ogni passaggio indicato di seguito può essere eseguito nella console; gli equivalenti da CLI sono forniti nei casi in cui fanno risparmiare tempo.
1. Crea il progetto ed esegui il push
Sezione intitolata “1. Crea il progetto ed esegui il push”pnpm dlx @rebasepro/cli init my-appcd my-appEsegui il commit e fai il push su un repository GitHub. .env è presente nel .gitignore e deve rimanere tale: l’app riceverà i propri valori al passaggio 5.
2. Crea il database
Sezione intitolata “2. Crea il database”Nella console, seleziona Create → Database:
- Version: 17 (quella predefinita) o 16. Qualsiasi versione a partire dalla 16 è supportata.
- Region: Frankfurt, accanto alla tua app.
outplane db create my-app-db --region aws-eu-central-1Dal pannello Connection del database, copia la stringa di connessione (nel formato psql), oppure visualizzala con outplane db url my-app-db. Out Plane richiede SSL su ogni connessione. Il tuo DATABASE_URL è quella stringa con sslmode=no-verify alla fine, al posto di qualsiasi sslmode già presente:
postgresql://<user>:<password>@<host>:5432/<database>?sslmode=no-verifyUsa no-verify, non require. Entrambi cifrano la connessione. Per psql, require significa anche “non verificare il certificato rispetto a un’autorità pubblica”, ma il driver Postgres su cui gira Rebase lo interpreta come “verificalo”, e un certificato del database non firmato pubblicamente fallisce quindi alla prima connessione con self-signed certificate. no-verify è il modo in cui il driver esprime ciò che require significa ovunque. La guida ufficiale di Node.js di Out Plane disattiva la verifica per lo stesso motivo. Lo stesso URL funziona per rebase db push dalla tua macchina: la CLI lo passa all’engine di schema Atlas come sslmode=require.
Il ruolo a cui Rebase passa
Sezione intitolata “Il ruolo a cui Rebase passa”Rebase applica la row-level security passando ciascuna richiesta autenticata a un ruolo con restrizioni, rebase_user. Al primo avvio, il runtime crea tale ruolo, assegna al ruolo indicato nella stringa di connessione il permesso di passare a esso e verifica che il passaggio funzioni prima di gestire qualsiasi richiesta. Non è necessario eseguire nulla manualmente.
Se il primo avvio si interrompe con un errore AppRoleSetupError che menziona rebase_user, il ruolo specificato nella stringa di connessione non ha i permessi per creare ruoli o per assegnarsi il cambio di ruolo. L’errore mostrerà l’istruzione SQL da eseguire: eseguila una volta sola con un ruolo del database autorizzato a creare ruoli, quindi effettua nuovamente il deploy.
Se le tue tabelle dichiarano una colonna col.vector(), il database richiede l’estensione pgvector. Lo scaffold iniziale non ne dichiara alcuna.
3. Crea un bucket
Sezione intitolata “3. Crea un bucket”In Buckets → Create bucket, creane uno e mantienilo private (l’impostazione predefinita). Rebase gestisce ogni download tramite le proprie API, e storageAuthorize in backend/storage.ts stabilisce chi può leggere, scrivere ed elencare i file.
Out Plane aggiunge un suffisso casuale al nome. Usa il nome completo visualizzato, non quello abbreviato digitato inizialmente.
Nella scheda Access del bucket, crea una chiave con autorizzazione Read and write. Il segreto viene mostrato una sola volta: copialo subito.
outplane bucket create my-app-uploadsoutplane bucket key create my-app-uploadsLe note di Out Plane relative al fatto che i caricamenti da browser necessitino di una regola CORS non si applicano in questo caso: il pannello di amministrazione e l’SDK di Rebase effettuano l’upload tramite le API, e il runtime scrive nel bucket direttamente dal server.
4. Aggiungi un Dockerfile
Sezione intitolata “4. Aggiungi un Dockerfile”Out Plane supporta la compilazione sia da Dockerfile sia tramite Buildpacks. Usa un Dockerfile: il progetto viene installato con pnpm e l’immagine compila autonomamente il bundle, per poi passarlo al runtime pubblicato. Esegui il commit di questo file nella root del progetto:
# Build the bundle from your sourceFROM node:22 AS buildWORKDIR /appCOPY . .RUN npx -y pnpm@11 install --frozen-lockfile && npx -y pnpm@11 run build
# The published runtime, with nothing added but the bundleFROM rebasepro/server:0.34.0COPY --from=build --chown=node:node /app/dist-bundle /bundleTre dettagli sono importanti:
node:22, nonnode:22-slim. L’installazione della CLI scarica l’engine di schema Atlas, che richiedecurle i certificati CA. L’immagine slim è priva di entrambi e l’installazione fallisce.--chown=node:node. Il runtime viene eseguito come utentenodee collega i propri pacchetti nel bundle all’avvio. Un bundle di proprietà di root viene comunque servito, ma registra un avviso per ogni pacchetto che non è riuscito a collegare.- Nessun sorgente nell’immagine finale. Contiene solo il runtime e il bundle compilato, e
dist-bundle/rimane nel gitignore.
L’immagine del runtime resta in ascolto sulla porta 8080 e la dichiara con EXPOSE, pertanto Out Plane precompila automaticamente la porta quando analizza il Dockerfile.
5. Crea l’app
Sezione intitolata “5. Crea l’app”Crea un’applicazione dalla console, collega il repository e il branch, quindi imposta:
| Campo | Valore |
|---|---|
| Build method | Dockerfile |
| Root directory | / |
| Port | 8080, HTTP, public |
| Start command | (lascia vuoto — verrà usato quello dell’immagine) |
outplane app create my-app --repo <owner>/<repo> --branch main --port 8080:http:publicIn Settings → Environment, scegli Edit as .env e incolla:
NODE_ENV=productionDATABASE_URL=postgresql://<user>:<password>@<host>:5432/<database>?sslmode=no-verifyJWT_SECRET=<openssl rand -hex 32>REBASE_SERVICE_KEY=<openssl rand -hex 32, a second one>CORS_ORIGINS=https://<your-app>.outplane.appFRONTEND_URL=https://<your-app>.outplane.appDISABLE_SELF_REGISTRATION=trueREBASE_ADMIN_EMAIL=you@example.comREBASE_ADMIN_PASSWORD=<at least 12 characters>STORAGE_TYPE=s3S3_BUCKET=<full bucket name, with its suffix>S3_REGION=autoS3_ENDPOINT=https://obj.outplane.devS3_ACCESS_KEY_ID=<access key>S3_SECRET_ACCESS_KEY=<secret>S3_FORCE_PATH_STYLE=falseQuindi fai clic su Save & deploy. Out Plane applica le modifiche alle variabili di ambiente solo al deployment successivo. Con la CLI, inserisci le stesse righe in un file ed esegui outplane env push --app my-app --deploy.
A cosa servono le righe meno evidenti:
NODE_ENV=production. Out Plane non la imposta automaticamente. Senza di essa, il runtime si avvia in modalità di sviluppo, in cui il primo utente sconosciuto che si registra diventa amministratore.REBASE_ADMIN_EMAILeREBASE_ADMIN_PASSWORD. In produzione il primo account che si registra non viene promosso ad amministratore; queste variabili definiscono quindi il primo amministratore. Il runtime crea l’account una sola volta, finché la tabella degli utenti è vuota. Consulta Il tuo primo amministratore.S3_FORCE_PATH_STYLE=false. Per impostazione predefinita, Rebase invia richieste path-style a un endpoint S3 personalizzato, poiché MinIO e la maggior parte degli storage self-hosted lo richiedono. I bucket di Out Plane accettano esclusivamente richieste di tipo virtual-hosted (https://<bucket>.obj.outplane.dev/…), e le richieste path-style falliscono. Questa riga è obbligatoria.S3_REGION=auto. I bucket Out Plane sono globali e i client firmano le richieste conauto.
L’indirizzo outplane.app dell’applicazione viene mostrato una volta creata l’app. Se differisce da quello previsto, correggi CORS_ORIGINS e FRONTEND_URL e seleziona nuovamente Save & deploy.
6. Aprila
Sezione intitolata “6. Aprila”Apri l’URL dell’app. Un unico container serve il pannello di amministrazione su / e le API su /api. Accedi con REBASE_ADMIN_EMAIL e REBASE_ADMIN_PASSWORD, quindi modifica la password.
Al primo avvio vengono create tutte le tabelle necessarie, comprese le tue, insieme alle relative policy di row-level security. Non c’è alcuna migrazione da eseguire prima. Carica un file dal pannello di amministrazione per verificare le impostazioni del bucket: un eventuale errore in questa fase indica quasi sempre che nel nome del bucket manca il suffisso oppure che manca S3_FORCE_PATH_STYLE=false.
Ogni push sul branch attiva un nuovo deploy. Per usare un dominio personalizzato, aggiungilo in Domains, collegalo alla porta 8080 dell’app e crea il record CNAME (o, per un dominio root, il record A) indicato nella console. Il certificato HTTPS viene rilasciato non appena il record si risolve. Successivamente, aggiungi la nuova origine a CORS_ORIGINS e FRONTEND_URL.
Singola istanza
Sezione intitolata “Singola istanza”Questa pagina configura una singola istanza, che rappresenta l’impostazione predefinita di Out Plane e il limite del piano Starter. Un solo container serve le API, il pannello di amministrazione, le funzionalità realtime, i cron job e la coda dei job.
I job pianificati continuerebbero a funzionare correttamente anche con più istanze: ogni esecuzione di cron viene acquisita in Postgres prima di avviarsi, perciò uno slot viene eseguito una sola volta indipendentemente dal numero di istanze che tentano di avviarlo. Altre funzionalità sono invece legate alla singola istanza — rate limiter, cache di trasformazione delle immagini, upload ripristinabili in corso — quindi leggi Più di un’istanza prima di aumentare il conteggio in Settings → Scale.
Archiviazione file
Sezione intitolata “Archiviazione file”I file caricati risiedono nel bucket Out Plane creato al passaggio 3, sopravvivendo quindi ai nuovi deploy, mentre il disco locale dell’app non contiene dati rilevanti.
Per effettuare la rotazione delle chiavi: creane una nuova nella scheda Access del bucket, impostala come S3_ACCESS_KEY_ID e S3_SECRET_ACCESS_KEY, fai clic su Save & deploy, quindi elimina la vecchia chiave. Out Plane segnala che una chiave eliminata può continuare a funzionare per un massimo di 15 minuti.
I permessi di lettura, scrittura ed elenco dei file sono gestiti da storageAuthorize in backend/storage.ts, indipendentemente dal bucket in cui si trovano. Consulta Storage.
Lo schema
Sezione intitolata “Lo schema”Il runtime crea le tabelle mancanti all’avvio, incluse quelle dichiarate in backend/schema. Il valore predefinito di REBASE_MIGRATE_ON_BOOT è ensure, che ha un comportamento additivo sull’intero schema. Crea tabelle, colonne e tipi enum mancanti e applica la loro row-level security, rendendo disponibile una nuova tabella già al deploy successivo.
ensure non modifica mai elementi già esistenti. Non altera il tipo di una colonna, non rimuove nulla né modifica i valori di un enum esistente, poiché un deploy non deve rimodellare uno schema come effetto collaterale.
Qualsiasi modifica che non sia puramente additiva — una colonna rinominata, un tipo reso più restrittivo, un campo rimosso — richiede l’esecuzione di rebase db push da una copia locale del repository:
pnpm exec rebase db push --dry-run --database-url '<your DATABASE_URL>'Esamina l’output SQL prodotto dal dry run, quindi eseguilo nuovamente senza --dry-run. Una modifica che comporta la perdita di dati richiede anche il flag --allow-destructive.
db push pianifica ogni modifica in una copia temporanea dello schema, all’interno di un database che ha lo stesso nome del tuo con il suffisso _dev_diff. Crealo una tantum nella scheda Access del database, assegnandogli come proprietario lo stesso ruolo del tuo database.
Per le migrazioni con versionamento, esegui il commit dei file di migrazione con rebase db generate ed esegui pnpm exec rebase db migrate --database-url '<your DATABASE_URL>' da una copia locale prima di effettuare il push. Out Plane non prevede uno step di release prima del deploy.
Prossimi passaggi
Sezione intitolata “Prossimi passaggi”- Deployment — la checklist per la produzione e le regole relative al primo amministratore comuni a tutte le piattaforme.
- Configuration — tutte le variabili di ambiente lette dal runtime.
- Storage — bucket, regole di accesso e gestione di più sorgenti di archiviazione contemporaneamente.