Deploy a Hono application

A Hono application runs on Sevalla as a Node.js application: Ingot, Sevalla’s builder, installs the dependencies with npm ci, compiles the TypeScript with the build script, and the web process runs the start script, node dist/index.js. The @hono/node-server adapter listens on the port that Sevalla sets in the PORT environment variable.

At a glance


Source	A Git repository
Build	Ingot (Node.js 24, npm), or the Dockerfile
Start command	`node dist/index.js`, 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.
Node.js 24 or later on your computer.

Create the project

Create a project from Hono’s nodejs template. The flags choose the template and npm, and install the dependencies without asking:

npm create hono@latest storefront -- --template nodejs --pm npm --install
cd storefront

The template installs Hono 4 and @hono/node-server, the adapter that runs Hono on Node.js, with TypeScript and tsx for development. Its package.json already has a build script, tsc, which compiles src/ to dist/, and a start script, node dist/index.js. Replace src/index.ts with a server that listens on PORT:

src/index.ts

import { serve } from '@hono/node-server'
import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => {
  return c.text('Hello from Hono on Sevalla')
})

const server = serve({
  fetch: app.fetch,
  port: Number(process.env.PORT) || 3000
}, (info) => {
  console.log(`Server is running on port ${info.port}`)
})

process.on('SIGTERM', () => {
  console.log('SIGTERM received, closing the server')
  server.close(() => process.exit(0))
})

serve() listens on all network interfaces when you don’t pass a hostname, and on PORT, which Sevalla sets to the web process’s port (8080 by default). On your computer, it uses port 3000.
When Sevalla stops an instance, during a deployment for example, it sends SIGTERM. server.close() stops new connections and lets requests in progress finish before the process exits. See How processes run.

Keep the build output out of the repository, next to node_modules/, which the template’s .gitignore already lists:

echo "dist/" >> .gitignore

Prepare the project for Sevalla

Pin the Node.js version in package.json:

npm pkg set engines.node="24.x"

File	Why Sevalla needs it
`package.json` `engines.node`	Ingot, the default build strategy, builds on the Node.js 24 line. Without it, Ingot uses its default line, which a new Ingot release can move. See Pin the Node.js version.
`package.json` `scripts.build` and `scripts.start`	Ingot runs `npm run build` during the build and starts the web process with the `start` script. The template set both.
`package-lock.json`	Ingot installs the exact versions in it with `npm ci`. Commit it.

Ingot needs no other configuration. After the build, it removes the devDependencies, TypeScript, tsx and @types/node, because node dist/index.js doesn’t need them. Run npm run dev and open http://localhost:3000 to check the server locally. Then commit everything and push it to your Git provider:

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

These steps build with Ingot. To build from your own Dockerfile instead, see Deploy with a Dockerfile.

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.

Deploy

Click the Overview tab, then click Deploy now under Recent deployments. Check the Branch and click Deploy.

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.

Verify the deployment

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 dist/index.js  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 ─╯

Wait for the deployment’s status to change to Deployed. The application’s status next to its name changes to Running.
Click the domain under the application’s name, for example storefront-x7k2m.sevalla.app. The page shows Hello from Hono on Sevalla.

The application header with its name, Running status, repository, branch and the domain that opens the application

To check from a terminal, read the deployment’s status with Get deployment and its build log with Get application deployment logs, as the last steps of Deploy with the API do, then request the domain:

curl -s https://storefront-x7k2m.sevalla.app/

Hello from Hono on Sevalla

If the deployment fails, read its build log, then see Troubleshoot Ingot builds. If it deploys but the domain doesn’t respond, check that the server reads PORT and read the application’s runtime logs.

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

FROM node:24-trixie-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

FROM node:24-trixie-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=build /app/package.json ./
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
USER 1000:1000
EXPOSE 8080
ENTRYPOINT ["tini", "--"]
CMD ["node", "dist/index.js"]

Line or choice	Why
`node:24-trixie-slim`	The Node.js 24 line that `engines.node` pins, on Debian 13, the image Ingot runs too. A line tag, not a digest, so each build picks up Node.js and Debian security fixes.
Two stages	The `build` stage installs every dependency and compiles TypeScript, then `npm prune --omit=dev` removes the devDependencies. The final stage copies only `package.json`, `node_modules` and `dist`.
`package.json` and `package-lock.json` copied before the source	A change to `src/` reuses the cached `npm ci` layer, so the build installs nothing again.
`tini`	Runs as PID 1 and passes `SIGTERM` on to Node.js, 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 `node` 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.

.dockerignore

.git
node_modules
dist
.env*
*.log
Dockerfile
.dockerignore

The .dockerignore keeps your local node_modules, the build output and local environment files out of the build, so the image gets what npm ci and npm run build produce. 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 7 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:

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.

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 Hono on Sevalla. See Dockerfile.

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.

Use environment variables

Add configuration on the application’s Environment variables tab and read it with process.env, as the server reads PORT. Variables marked Available during buildtime also reach npm ci and npm run build; with a Dockerfile, they arrive as build arguments, which a stage reads only after an ARG line for each one. Variables apply at the next deployment. See Environment variables.

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 the web process first. See Custom domains.

Deploy with the API

The Sevalla API makes the same deployment as 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 command and the MCP server 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 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. 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.

Find the location

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 lists them all.

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.

Create the application

Create application (createApplicationV3) creates the application with the Ingot build strategy and a web process, and doesn’t deploy it.

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

CLI:

sevalla apps create --name storefront --cluster "$CLUSTER_ID" --source privateGit --git-type github --repository https://github.com/acme/storefront --branch main

. MCP: create_application with deploy set to false.

Find the web process

List processes (listProcessesV3) returns the web process that Create application added:

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

CLI: sevalla apps processes list --app-id "$APP_ID". MCP: get_application, in processes.

Find the H1 size

The API creates the web process with the S1 size, where the dashboard picks H1. List process resource types (listProcessResourceTypesV3) returns the ID of each size:

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

CLI: sevalla resources process-types. MCP: get_platform_options.

Set the web process size

Update process (updateProcessV3) sets the size, which applies at the first deployment:

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 -r .resource_type_name

h1

CLI: sevalla apps processes update "$WEB_ID" --app-id "$APP_ID" --resource-type "$H1_ID". MCP: scale_process with size_id, and apply_now set to false.

Turn on auto-deploy

Update application (updateApplicationV3) with auto_deploy deploys every push to the branch:

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 -r .auto_deploy

true

CLI: sevalla apps update "$APP_ID" --data '{"auto_deploy":true}'. MCP: sevalla_api_update with updateApplicationV3, the application ID as path_params.id and the same body.

Choose the Dockerfile build strategy

Skip this step to build with Ingot. To build from the Dockerfile instead, Update application (updateApplicationV3) sets the build strategy:

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 -r .build_type

dockerfile

CLI: sevalla apps update "$APP_ID" --data '{"build_type":"dockerfile","dockerfile_path":"Dockerfile","docker_context":"."}'. MCP: sevalla_api_update with updateApplicationV3 and the same body.

Deploy

Trigger deployment (triggerDeploymentV3) deploys the latest commit of the branch:

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)

CLI: sevalla apps deployments trigger "$APP_ID". MCP: trigger_deployment.

Wait for the deployment

Get deployment (getDeploymentV3) returns the deployment’s status: waiting, inProgress, then success, failed, cancelled or skipped. Poll it until the deployment ends:

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"

success

The loop asks every 15 seconds, for up to 30 minutes, and keeps asking through an empty or failed reply. success means the application is deployed. CLI: sevalla apps deployments get "$DEPLOYMENT_ID" --app-id "$APP_ID". MCP: get_deployment.

Read the build log

Get application deployment logs (getApplicationDeploymentLogsV3) returns the build log, one line per entry. With Ingot, the Start row of the build plan shows the start command:

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' | grep '│ Start' | tr -s ' '

│ Start node dist/index.js package.json scripts.start │

With a Dockerfile, the log shows 📦 Building and pushing docker image using Dockerfile... in place of the build plan. When a deployment fails, the end of this log says why. CLI: sevalla apps deployments logs "$DEPLOYMENT_ID" --app-id "$APP_ID". MCP: get_deployment_logs.

Check the application

List application domains (listApplicationDomainsV3) returns the application’s domains. Request the application on its domain:

DOMAIN=$(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://$DOMAIN/"

Hello from Hono on Sevalla

CLI: sevalla apps domains list --app-id "$APP_ID". MCP: get_application, in domains.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java and Kotlin

.NET

Elixir

Static site generators

Deploy a Hono application

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Deploy with a Dockerfile

Deploy changes

Use environment variables

Add a custom domain

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Create the project

​Prepare the project for Sevalla

​Deploy to Sevalla

​Verify the deployment

​Deploy with a Dockerfile

​Deploy changes

​Use environment variables

​Add a custom domain

​Deploy with the API

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Deploy with a Dockerfile

Deploy changes

Use environment variables

Add a custom domain

Deploy with the API