> ## Documentation Index > Fetch the complete documentation index at: https://docs.sevalla.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > These are the docs for Sevalla, a platform for deploying applications, databases, static sites, object storage and load balancers. The dashboard is at https://app.sevalla.com. > Bold text in steps is an exact dashboard label. > To act on a Sevalla account, prefer the Sevalla MCP server (https://mcp.sevalla.com/mcp, see https://docs.sevalla.com/ai-agents/overview.md), then the Sevalla CLI (https://docs.sevalla.com/developer-tools/cli.md), then the REST API (https://api-docs.sevalla.com, OpenAPI spec at https://api.sevalla.com/v3/openapi.json). > Every page index is at https://docs.sevalla.com/llms.txt. # Deploy an Elysia application > Deploy an Elysia 1.4 server on Bun to Sevalla from a Git repository: listen on PORT, pin Bun in engines.bun, and build with Ingot or a Dockerfile. An Elysia application runs on Sevalla as a Bun application: Ingot, Sevalla's builder, sees `bun.lock` in your Git repository, installs Bun and the dependencies, and the web process runs the `start` script, `bun src/index.ts`. Elysia's `listen()` takes the port that Sevalla sets in the `PORT` environment variable. ## At a glance | | | | - | - | | Source | A Git repository | | Build | [Ingot](https://docs.sevalla.com/applications/builds/ingot.md) (Bun 1), or the [Dockerfile](#deploy-with-a-dockerfile) | | Start command | `bun src/index.ts`, from `scripts.start` in `package.json` | | Port | The `PORT` environment variable, `8080` by default | | Processes | Web process | | Services | None | | Disk | None | | Size | **H1** for the web process | ### Environment variables The application needs no environment variables of its own. Sevalla sets `PORT` for the web process. ## Before you begin * A Sevalla company with a payment method, and a GitHub, GitLab or Bitbucket account for the repository. See [Git providers](https://docs.sevalla.com/git/overview.md). * Bun 1.4 or later on your computer. ## Create the project Create a project with Elysia's template: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} bun create elysia storefront cd storefront ``` `bun create elysia` writes `src/index.ts`, `package.json`, `bun.lock`, `tsconfig.json` and a `.gitignore`, installs Elysia 1.4, and creates a Git repository with a first commit. Replace `src/index.ts` with a server that listens on `PORT`: ```ts src/index.ts theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} import { Elysia } from "elysia"; const app = new Elysia() .get("/", () => "Hello from Elysia on Sevalla") .listen(process.env.PORT ?? 3000); console.log(`🦊 Elysia is running on port ${app.server?.port}`); process.on("SIGTERM", async () => { console.log("SIGTERM received, closing the server"); await app.stop(); process.exit(0); }); ``` * `listen()` passes the port to `Bun.serve()`, which listens on all network interfaces (`0.0.0.0`) by default. Sevalla sets [`PORT`](https://docs.sevalla.com/guides/javascript/overview#listen-on-the-port-environment-variable) to the web process's port (`8080` by default). On your computer, the server uses port 3000. * When Sevalla stops an instance, during a deployment for example, it sends `SIGTERM`. `app.stop()` stops accepting connections and waits for requests in progress before the process exits. See [How processes run](https://docs.sevalla.com/applications/processes.md#how-processes-run). ## Prepare the project for Sevalla Set the start command and pin the Bun version in `package.json`: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} bun pm pkg set scripts.start="bun src/index.ts" engines.bun="1.x" ``` | File | Why Sevalla needs it | | - | - | | `package.json` `scripts.start` | [Ingot](https://docs.sevalla.com/applications/builds/ingot.md), the default build strategy, starts the web process with it. The template has no `start` script, and its `module` field names `src/index.js`, a file the project doesn't have. | | `package.json` `engines.bun` | `1.x` follows the newest Bun 1 release, so each build gets its fixes. Without it, Ingot uses its default Bun line, which a new Ingot release can move. | | `bun.lock` | Ingot detects Bun from it and installs the exact versions in it with `bun install --frozen-lockfile`. Commit it: without it, Ingot builds the project with npm and Node.js. | Bun runs TypeScript directly, so the project needs no build step. Ingot removes the devDependencies, such as `bun-types`, after the install. It builds Bun applications on its Node.js image and adds Bun to it, so the build plan also names Node.js. See [Deploy a Bun application](https://docs.sevalla.com/guides/javascript/bun.md). Run `bun run dev` and open `http://localhost:3000` to check the server locally. Then commit everything and push it to your Git provider. The repository already exists, so there's no `git init`: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} git add . git commit -m "Prepare for Sevalla" git branch -M main git remote add origin https://github.com/acme/storefront.git git push -u origin main ``` ## Deploy to Sevalla These steps build with [Ingot](https://docs.sevalla.com/applications/builds/ingot.md). To build from your own Dockerfile instead, see [Deploy with a Dockerfile](#deploy-with-a-dockerfile). **1. Create the application** In the sidebar, click **Applications**, then click **Create** > **Application**. Under **Source**, click **Private repository**, then choose the **Git provider**, the **Repository** and the **Branch**. Under **Location**, choose a **Data center**. Keep the **Size** at **H1** or choose a larger one, then click **Create application**. The application opens on its **Overview** tab with the status **Not deployed yet**: creating an application doesn't deploy it. **2. Deploy** Click the **Overview** tab, then click **Deploy now** under **Recent deployments**. Check the **Branch** and click **Deploy**. **3. Turn on auto-deploy** To deploy every push to the branch automatically, click the **Settings** tab, then click **Update auto-deploy** in the **Auto-deploy** section. Turn on **Auto-deploy** and click **Update auto-deploy**. See [Deployments](https://docs.sevalla.com/applications/deployments.md#deploy-automatically-on-push). ## Verify the deployment 1. On the **Deployments** tab, click the deployment. Its **Build log** shows Ingot's [build plan](https://docs.sevalla.com/applications/builds/ingot.md#read-the-build-plan): Bun 1 and the Bun package manager, both at the `"1.x"` in `engines.bun`, and the start command from the `start` script. ```text Build log theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} ╭─ ■ Node.js 24 application ────────────────────────────────────╮ │ Node.js 24 default │ │ Bun 1 package.json engines "1.x" │ │ Package manager bun 1.x package.json engines │ │ Start bun src/index.ts package.json scripts.start │ │ DevDependencies removed after the build │ ├─ Image ───────────────────────────────────────────────────────┤ │ Build node:24-trixie │ │ Runtime node:24-trixie-slim │ │ User 1000:1000 │ │ Init tini │ │ Port $PORT, default 8080 │ ╰──────────────────────────────────────────────── Ingot v0.4.1 ─╯ ``` 2. Wait for the deployment's status to change to **Deployed**. The application's status next to its name changes to **Running**. 3. Click the domain under the application's name, for example `storefront-x7k2m.sevalla.app`. The page shows `Hello from Elysia on Sevalla`. ![The application header with its name, Running status, repository, branch and the domain that opens the application](https://assets.sevalla.com/screenshots/light/app-overview-address.png) To check from a terminal, read the deployment's status with [Get deployment](https://api-docs.sevalla.com/v3/applications/get-deployment) and its build log with [Get application deployment logs](https://api-docs.sevalla.com/v3/applications/get-application-deployment-logs), as the last steps of [Deploy with the API](#deploy-with-the-api) do, then request the domain: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl -s https://storefront-x7k2m.sevalla.app/ ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} Hello from Elysia on Sevalla ``` If the deployment fails, read its build log, then see [Troubleshoot Ingot builds](https://docs.sevalla.com/applications/builds/ingot.md#troubleshoot-ingot-builds). A build plan without a **Bun** row means Ingot didn't find `bun.lock` in the repository. ## Deploy with a Dockerfile Ingot needs no Dockerfile. Write your own when you want full control of the image: the base image, the system packages and every layer. Add a `Dockerfile` and a `.dockerignore` to the root of the repository: ```dockerfile Dockerfile theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} FROM oven/bun:1-slim AS deps WORKDIR /app COPY package.json bun.lock ./ RUN bun install --frozen-lockfile --production FROM oven/bun:1-slim # hadolint ignore=DL3008 RUN apt-get update \ && apt-get install -y --no-install-recommends tini \ && rm -rf /var/lib/apt/lists/* WORKDIR /app ENV NODE_ENV=production COPY --from=deps /app/node_modules ./node_modules COPY package.json ./ COPY src ./src USER 1000:1000 EXPOSE 8080 ENTRYPOINT ["tini", "--"] CMD ["bun", "src/index.ts"] ``` | Line or choice | Why | | - | - | | `oven/bun:1-slim` | Bun's official image on Debian 13, on the Bun 1 line that `engines.bun` pins. A line tag, not a digest, so each build picks up Bun and Debian fixes. | | Two stages | The `deps` stage installs the production dependencies from `bun.lock` and leaves out `bun-types`. The final stage copies `node_modules` without Bun's download cache. | | `package.json` and `bun.lock` copied before the source | A change to `src/` reuses the cached install layer. | | `tini` | Runs as PID 1 and passes `SIGTERM` on to Bun, so the server's `SIGTERM` handler runs. It comes from Debian's packages, unpinned so that rebuilds get its fixes, which is why the line before it tells hadolint to skip its version-pinning check. | | `USER 1000:1000` | The image's `bun` user, not root. The copied files stay owned by root, so the server can read its code but not change it. | | `EXPOSE 8080` | Documents Sevalla's default `PORT`. The server reads `PORT` when it starts. | ```text .dockerignore theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} .git node_modules .env* *.log Dockerfile .dockerignore ``` Commit and push both files. Ingot doesn't use the `Dockerfile`, so you can keep it in a repository that builds with Ingot, but it adds the `.dockerignore` patterns to its own: its build plan then shows `Ignored 6 patterns from .dockerignore`, and the Ingot build still passes because none of these patterns removes a file it needs. Then switch the application to the Dockerfile build strategy: **1. Choose the Dockerfile build strategy** On the application's **Settings** tab, in the **Build strategy** section, click **Update build strategy**. Click **Dockerfile**, keep the **Dockerfile path** `Dockerfile` and the **Docker context** `.`, then click **Update build strategy**. **2. Deploy** Click the **Overview** tab, then click **Deploy now** under **Recent deployments**. Check the **Branch** and click **Deploy**. The deployment's build log shows `📦 Building and pushing docker image using Dockerfile...` instead of Ingot's build plan, and its **Dockerfile** tab shows your file. When the deployment's status is **Deployed**, the domain shows `Hello from Elysia on Sevalla`. See [Dockerfile](https://docs.sevalla.com/applications/builds/dockerfile.md). ## Deploy changes With **Auto-deploy** on, every push to the branch starts a deployment; otherwise, click **Deploy now** for each change. Each deployment builds the image, then replaces the web process's instances. See [Deployments](https://docs.sevalla.com/applications/deployments.md). ## Use environment variables Add configuration on the application's **Environment variables** tab and read it with `process.env` or `Bun.env`. Variables apply at the next deployment. See [Environment variables](https://docs.sevalla.com/applications/environment-variables.md). ## Add a custom domain To serve the application from your own domain, such as `shop.example.com`, add the domain on the application's **Domains** tab and create the DNS records that Sevalla shows. Custom domains need a web process larger than **H1**, so [scale](https://docs.sevalla.com/applications/scaling.md) the web process first. See [Custom domains](https://docs.sevalla.com/domains/overview.md). ## Deploy with the API The [Sevalla API](https://docs.sevalla.com/developer-tools/api.md) makes the same deployment as [Deploy to Sevalla](#deploy-to-sevalla) without the dashboard. Run the steps in order in one shell: each step is one API call, and saves the IDs that later steps need in shell variables. Each step also names the [CLI](https://docs.sevalla.com/developer-tools/cli.md) command and the [MCP server](https://docs.sevalla.com/ai-agents/overview.md) tool that do the same. A variable that holds `null` means the call failed: run the `curl` command without its `jq` part to read the error. You need: * An [API key](https://docs.sevalla.com/developer-tools/api-keys.md) with the **Company developer** role, or the `APP:CREATE`, `APP:READ` and `APP:UPDATE` permissions, in the `SEVALLA_API_KEY` environment variable. The CLI reads the key from `SEVALLA_API_TOKEN`. * The repository on GitHub, GitLab or Bitbucket, and a Git account that can read it connected to your Sevalla user, which only the dashboard can do. See [Git providers](https://docs.sevalla.com/git/overview.md). Creating the application checks the access: if Sevalla can't read the repository, the call returns `400` with `Cannot access repository https://github.com/acme/storefront: Repository not found or you don't have access.`, followed by where to grant the access. * `curl` and `jq`. **1. Find the location** [List clusters](https://api-docs.sevalla.com/v3/resources/list-clusters) (`listClustersV3`) returns every location with its `id`, its name in `display_name` and its region ID in `location`. Pick one by its region ID, here `eu-frankfurt-1` for Frankfurt, Germany. [Locations](https://docs.sevalla.com/platform/locations.md) lists them all. ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} CLUSTER_ID=$(curl -s https://api.sevalla.com/v3/resources/clusters \ -H "Authorization: Bearer $SEVALLA_API_KEY" \ | jq -r '.[] | select(.location == "eu-frankfurt-1") | .id') ``` CLI: `sevalla resources clusters`. MCP: `get_platform_options`. **2. Create the application** [Create application](https://api-docs.sevalla.com/v3/applications/create-application) (`createApplicationV3`) creates the application with the Ingot build strategy and a web process, and doesn't deploy it. ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} APP_ID=$(curl -s -X POST https://api.sevalla.com/v3/applications \ -H "Authorization: Bearer $SEVALLA_API_KEY" \ -H "Content-Type: application/json" \ -d @- <