Dreambase Docs

What it does

When you deploy a codebase service, Dreambase dispatches a DEPLOYMENT_CREATED eventto App Hosting. The service takes the project's git source (for example a GitHub repository), pushes it to the chosen hosting provider, configures its environment variables (including any supplied by connected dependencies), and reports the resulting deployment URL and status back into the Dreambase API. When those variables later change, Dreambase emits DEPLOYMENT_ENV_CHANGED and the service applies them by redeploying.

Built on NestJS

App Hosting is a NestJS application that can run as a single Vercel serverless function. It exposes a webhook per provider and translates Dreambase events into the provider's own deployment API.

Supported providers

Vercel — deploy an app from git sources (such as GitHub repositories) to Vercel, including environment variables. This is the reference, fully-wired provider.
Railway— deploy a git-sourced app to Railway's container platform through its GraphQL API, including environment variables.
Netlify — deploy to Netlify through its API, with environment-variable support.
AWS — provision and deploy to AWS infrastructure.
Server— a multi-purpose target that can deploy code from various sources to various destinations, for cases the managed providers don't cover.

Integrations

The wired-up providers each have a dedicated reference page:

Vercel

Deploy a git-sourced app to Vercel and report its live URL.

Railway

Deploy a git-sourced app to Railway and report its live URL.

Server

A deployment-less placeholder for an external or unmanaged host.

App scaffolds

These integrations represent an application in your design rather than a hosting provider. You choose a host, fill in the app details and README, and download the scaffolded project as a ready-to-run .zip — no deployment required.

Next.js

Scaffold a Next.js (App Router) app, pick a host, and download the project.

Express.js

Scaffold an Express (TypeScript) app, pick a host, and download the project.

Webhook

Each provider exposes a webhook that Dreambase calls. The Vercel provider is the canonical example:

POST/vercel/webhook

Deploy & manage a git-sourced app on Vercel

Events it handles

WEBHOOK_CHALLENGE — verify the webhook endpoint.
DEPLOYMENT_CREATED— create a deployment on the provider from the service's git source and report back its URL and status.
DEPLOYMENT_DELETED — remove a deployment from the provider.
DEPLOYMENT_ENV_CHANGED — apply changed environment variables (on Vercel, by redeploying and then removing the previous deployment).
DEPLOYMENT_STATUS_CHANGED— reconcile the hosted resource with the deployment's status; when it becomes STOPPED the deployment is removed from the provider.
HEALTH_CHECK — confirm a hosted deployment is reachable.

Configuring a Vercel service

The Vercel provider deploys a git-sourced project to Vercel and polls the deployment to completion before reporting back. Configure it with these inputs on the service:

Input	Required	Description
`gitOwner`	yes	Repository owner, organization, or username (e.g. `my-org`).
`gitRepo`	yes	Repository name to deploy (e.g. `my-app`).
`vercelToken`	yes	A Vercel API token with deploy access. Accepts a `{{env.KEY}}` reference so the secret stays out of the canvas.
`gitProvider`	optional	Git host: `github` (default), `gitlab`, or `bitbucket`.
`gitBranch`	optional	Branch to deploy. Defaults to `main`.
`target`	optional	Vercel target: `production` (default) or `preview`.
`projectName`	optional	Vercel project name. Defaults to the repository name.
`vercelTeamId`	optional	Vercel team/scope id the project belongs to.
`framework`, `rootDirectory`, `buildCommand`, `installCommand`, `outputDirectory`, `nodeVersion`	optional	Build overrides. Leave empty to let Vercel auto-detect.

On a successful deployment the service writes two outputs back to Dreambase:

url — the live URL of the Vercel deployment.
vercelDeploymentId— the deployment's id on Vercel, used to tear it down on DEPLOYMENT_DELETED, on a DEPLOYMENT_STATUS_CHANGED to STOPPED, and to reap the previous deployment after a DEPLOYMENT_ENV_CHANGED redeploy.

Configuration

The service calls back into the API at DREAMBASE_API_URL (default http://localhost:3005) and talks to Vercel at VERCEL_API_URL (default https://api.vercel.com). It runs on PORT 3007 locally.

Environment variables flow through

Outputs from services this app depends on — a database connection string, an API key — are mapped to environment variables by the connector between them, seeded onto the deployment when it is created, and set on the provider during deployment, so your hosted app comes up already wired to the rest of the project. If a dependency later publishes new outputs, Dreambase emits DEPLOYMENT_ENV_CHANGED and the deployment is updated with the new values.

Deployment

The service is designed to run as a Vercel serverless function: a single build compiles the NestJS app, and all provider routes are served from one handler. It can equally run as a long-lived Node process if you prefer to host it yourself.