Deploy a Koa application

​

At a glance

​

Environment variables

​

Before you begin

• A Sevalla company with a payment method, and a GitHub, GitLab or Bitbucket account for the repository. See Git providers.
• Node.js 24 or later on your computer.

​

Create the project

mkdir storefront && cd storefront
npm init -y
npm install koa @koa/router

import Koa from "koa";
import Router from "@koa/router";

// Trust the X-Forwarded-* headers from Sevalla's load balancer
const app = new Koa({ proxy: true });
const router = new Router();

router.get("/", (ctx) => {
  ctx.body = `Hello from Koa on Sevalla over ${ctx.protocol}`;
});

app.use(router.routes()).use(router.allowedMethods());

const port = process.env.PORT || 3000;
const server = app.listen(port, () => {
  console.log(`Listening on port ${port}`);
});

process.on("SIGTERM", () => {
  console.log("SIGTERM received, closing the server");
  server.close();
});

node_modules/

​

Prepare the project for Sevalla

npm pkg set type=module scripts.start="node server.js" engines.node="24.x"

• It reads PORT, which Sevalla sets to the web process’s port (8080 by default), and app.listen(port) listens on all network interfaces.
• Sevalla’s load balancer ends HTTPS and forwards each request to the instance over HTTP, with the original protocol and client address in the X-Forwarded-Proto and X-Forwarded-For headers. proxy: true makes Koa read them, so ctx.protocol is https, ctx.secure is true and ctx.ip is the visitor’s address. Without it, Koa sees every request as http, and setting a cookie with secure: true fails.
• Sevalla sends SIGTERM to each instance it replaces during a deployment. server.close() stops accepting connections and lets the requests in progress finish, then Node.js exits.

git init
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

​

Verify the deployment

1. On the Deployments tab, click the deployment. Its Build log shows Ingot’s build plan: Node.js 24 from engines.node, npm from package-lock.json and the start command from the start script.
   Build log

   ╭─ ■ Node.js 24 application ───────────────────────────────────╮
   │ Node.js          24              package.json engines "24.x" │
   │ Package manager  npm             package-lock.json           │
   │ Start            node server.js  package.json scripts.start  │
   ├─ 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 Koa on Sevalla over https: Koa read the protocol from the load balancer’s X-Forwarded-Proto header.
4. Check the same address from a terminal:
   curl -s https://storefront-x7k2m.sevalla.app/
   
   Hello from Koa on Sevalla over https
   

​

Deploy with a Dockerfile

FROM node:24-trixie-slim

WORKDIR /app
ENV NODE_ENV=production PORT=8080

COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY . .

USER 1000:1000
EXPOSE 8080
CMD ["node", "server.js"]

.git
node_modules
npm-debug.log*
.env*
Dockerfile
.dockerignore

​

Deploy changes

​

Use environment variables

​

Add a custom domain

​

Connect a database

​

Troubleshoot

​

Deploy with the API

• An API key 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 a Git provider that’s connected to your Sevalla account. See Git providers. Creating the application checks it: when 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 access.
• curl and jq.

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')

H1_ID=$(curl -s https://api.sevalla.com/v3/resources/process-resource-types \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.[] | select(.name == "h1") | .id')

APP_ID=$(curl -s -X POST https://api.sevalla.com/v3/applications \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"storefront","cluster_id":"'"$CLUSTER_ID"'","source":"privateGit","git_type":"github","repo_url":"https://github.com/acme/storefront","default_branch":"main"}' \
  | jq -r .id)

WEB_ID=$(curl -s https://api.sevalla.com/v3/applications/$APP_ID/processes \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.data[] | select(.type == "web") | .id')

curl -s -X PATCH https://api.sevalla.com/v3/applications/$APP_ID/processes/$WEB_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_type_id":"'"$H1_ID"'"}' \
  | jq -c '{resource_type_name, cpu_limit, memory_limit}'

{"resource_type_name":"h1","cpu_limit":300,"memory_limit":300}

curl -s -X PATCH https://api.sevalla.com/v3/applications/$APP_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_deploy":true}' | jq .auto_deploy

DEPLOYMENT_ID=$(curl -s -X POST https://api.sevalla.com/v3/applications/$APP_ID/deployments \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r .id)

for i in $(seq 1 120); do
  STATUS=$(curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"

curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID/logs?limit=5000" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.[].message'

HOST=$(curl -s https://api.sevalla.com/v3/applications/$APP_ID/domains \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.data[] | select(.is_primary) | .name')
curl -s https://$HOST/

Hello from Koa on Sevalla over https

​

Build from the Dockerfile with the API

curl -s -X PATCH https://api.sevalla.com/v3/applications/$APP_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"build_type":"dockerfile","dockerfile_path":"Dockerfile","docker_context":"."}' \
  | jq -c '{build_type, dockerfile_path, docker_context}'

{"build_type":"dockerfile","dockerfile_path":"Dockerfile","docker_context":"."}