Deploy a Remix application

A Remix 3 application runs on Sevalla as an application: Ingot, Sevalla’s builder, installs it from your Git repository, and the web process runs the starter’s start script, which runs server.ts with Node.js and listens on the port that Sevalla sets in the PORT environment variable. Remix 2 applications continue as React Router: see Deploy a React Router application.

At a glance


Source	A Git repository
Build	Ingot (Node.js 24, npm, no build step), or the Dockerfile
Start command	`NODE_ENV=production node --import remix/node-tsx server.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 to the web process’s port.

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.3 or later on your computer. Remix 3 needs it.

Create the project

Create a project with the Remix CLI and install its dependencies:

npx remix@latest new storefront
cd storefront
npm install

The starter comes with a .gitignore and a start script that runs the TypeScript server directly, with no build step:

package.json

{
  "scripts": {
    "start": "NODE_ENV=production node --import remix/node-tsx server.ts"
  },
  "engines": {
    "node": ">=24.3.0"
  }
}

Prepare the project for Sevalla

Pin the Node.js version to the 24 line, from 24.3 up:

npm pkg set engines.node="^24.3.0"

The starter’s >=24.3.0 lets Ingot pick its default line, Node.js 24 today, which a new Ingot release can move. ^24.3.0 keeps the build on Node.js 24 and keeps Remix’s minimum. See Pin the Node.js version. The rest of the starter is ready to deploy:

Ingot installs the dependencies with npm ci and starts the web process with the start script. The project has no build script, so there’s no build step.
server.ts takes its port from PORT, which Sevalla sets to the web process’s port (8080 by default), and server.listen(port) listens on all network interfaces. Without PORT, it uses port 44100.
Ingot removes the devDependencies (typescript and @types/node) from the image. The server doesn’t need them: remix/node-tsx, part of the remix package, loads the TypeScript files.

Run npm start and open http://localhost:44100 to check the server locally. Then commit everything, including package-lock.json, 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, with no framework detected.

Build log

╭─ ■ Node.js 24 application ──────────────────────────────────────────────────────────────────────────────────╮
│ Node.js          24                                                          package.json engines "^24.3.0" │
│ Package manager  npm                                                         package-lock.json              │
│ Start            NODE_ENV=production node --import remix/node-tsx server.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.5.0 ─╯

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 Remix starter’s home page opens.

Check the same address from a terminal:

curl -s https://storefront-x7k2m.sevalla.app/ | grep -o '<title>[^<]*</title>'

<title>Storefront</title>

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

With the API, Get deployment (getDeploymentV3) returns the deployment’s status, success once it’s deployed, and Get application deployment logs (getApplicationDeploymentLogsV3) returns its build log, which ends with Web has been deployed successfully. See Deploy with the API. If the deployment fails, read its build log, then see Troubleshoot Ingot builds. If the server doesn’t start, read the application’s runtime logs.

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.

Store sessions and files outside the instance

Remix’s memory session storage and local upload folders only work while one instance runs and until the next deployment. Use Remix’s Redis session storage with a Sevalla Redis database, and its S3 file storage with Sevalla object storage, before you run more than one instance.

Deploy a React Router application

Remix 2 continued as React Router, so an application upgraded from Remix 2, or created with create-react-router, uses React Router’s server:

npx create-react-router@latest storefront --yes
cd storefront
npm pkg set engines.node="24.x"

Ingot detects React Router, runs the build script (react-router build), and starts the web process with the start script, react-router-serve ./build/server/index.js. react-router-serve takes its port from PORT, and Ingot sets HOST to 0.0.0.0, so it listens on all network interfaces.
engines.node keeps the build on Node.js 24 when a new Ingot release moves its default line.
The template’s Dockerfile isn’t used: Ingot writes its own, and applies the template’s .dockerignore on top of its own patterns.

Commit and push the project, then follow the steps in Deploy to Sevalla, or make the calls in Deploy with the API. The build plan’s Framework row shows React Router, and the starter’s home page opens on the application’s domain: the curl command in Verify the deployment prints <title>New React Router App</title>. A Remix 2 application that still uses @remix-run/* packages deploys the same way: Ingot detects @remix-run/dev, and its start script runs remix-serve, which also reads PORT.

Deploy with a Dockerfile

Ingot needs no Dockerfile. Write one when you want full control of the image: the base image, the system packages and every layer. For the Remix 3 starter, add a Dockerfile and a .dockerignore to the root of the repository:

Dockerfile

FROM node:24-trixie AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:24-trixie-slim
WORKDIR /app
ENV NODE_ENV=production PORT=8080
COPY --from=deps /app/node_modules ./node_modules
COPY . .
USER 1000:1000
EXPOSE 8080
CMD ["node", "--import", "remix/node-tsx", "server.ts"]

Line or choice	Why
`node:24-trixie`, then `node:24-trixie-slim`	Node.js 24, the line that `engines.node` pins, on Debian 13. The first stage has the compilers that native modules need; the slim final image leaves them out. A line tag picks up Node.js and Debian security fixes at every build, which a digest would stop.
Two stages	The first stage installs the production dependencies with `npm ci --omit=dev`. The final image gets them and the source: Remix runs the TypeScript files directly, with no build step.
The lock file before the source	`npm ci` installs exactly what `package-lock.json` lists, and the build cache reuses that layer until the lock file changes, so a code change doesn’t reinstall the dependencies.
`USER 1000:1000`	The server runs as the image’s `node` user, not as root. Root owns the copied files, so the server can’t change its own code.
`NODE_ENV=production`	Does what the `start` script’s `NODE_ENV=production` does: Remix’s asset server minifies the browser scripts and serves no source maps.
`CMD` in exec form	Runs the `start` script’s command without npm in between, so Node.js is the container’s main process and gets `SIGTERM` when an instance stops. The starter’s `server.ts` handles it: it closes the server and every open connection, then exits.
`PORT=8080`, `EXPOSE 8080`	`server.ts` listens on `PORT`. Sevalla sets it to the web process’s port; `8080` is the default when you run the image yourself.

.dockerignore

.git
node_modules
.env*
*.log
**/*.test.*
Dockerfile
.dockerignore

The .dockerignore keeps installed packages, local environment files and the starter’s tests out of the image. Commit and push both files. Ingot doesn’t use the Dockerfile and adds your .dockerignore patterns to its own, so you can keep both files in a repository that builds with Ingot. 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 status changes to Deployed, the application’s domain opens the Remix starter’s home page, and the curl command in Verify the deployment prints <title>Storefront</title>. See Dockerfile for build arguments and private base images, and Deploy with the API to switch the build strategy with the API.

Use a Dockerfile for React Router

The create-react-router template comes with a Dockerfile that runs the server as root. Replace it, and the template’s .dockerignore, with these:

Dockerfile

FROM node:24-trixie 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
WORKDIR /app
ENV NODE_ENV=production PORT=8080
COPY package.json ./
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/build ./build
USER 1000:1000
EXPOSE 8080
CMD ["node_modules/.bin/react-router-serve", "./build/server/index.js"]

.dockerignore

.git
.react-router
build
node_modules
.env*
*.log
Dockerfile
.dockerignore

The build stage runs react-router build, then removes the devDependencies. The final image gets build, package.json and the production dependencies, which include react-router-serve. CMD runs the start script’s command without npm in between: react-router-serve listens on PORT on all network interfaces, and on SIGTERM it finishes the requests in progress, then exits. The other choices are the same as for the Remix 3 Dockerfile. Switch the build strategy and deploy with the steps in Deploy with a Dockerfile; the starter’s home page opens on the application’s domain.

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.

Connect a database

Create a database in the same location as the application, then connect the application to it with Add environment variables to the application turned on. Sevalla adds DB_URL, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME and DB_PASSWORD to the application (what each one holds), and they apply at the next deployment. Read them in server.ts or in actions with process.env.DB_URL.

Deploy with the API

These calls make the same deployment as Deploy to Sevalla, in an order that a script or an AI agent runs as it is. Each step names the Sevalla API operation, then the CLI command and the MCP server tool that do the same. 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 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.

Choose the location

List clusters (listClustersV3) returns the locations your company can use, each with its id, its display_name and its region ID in location (see Locations). Keep the ID of the one you want, here Frankfurt, Germany:

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.

Find the H1 size

List process resource types (listProcessResourceTypesV3) returns the sizes by name, in lowercase:

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.

Create the application

Create application (createApplicationV3) creates the application with a web process and auto-deploy off. It builds with Ingot (build_type is ingot) and isn’t deployed yet:

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)

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, because it deploys by default.

Find the web process

List processes (listProcessesV3) returns the web process that the application was created with:

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.

Set the size

The API creates the web process at S1, where the dashboard’s default is H1. Update process (updateProcessV3) sets H1:

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}

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) turns on automatic deployments for 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 .auto_deploy

CLI: sevalla apps update $APP_ID --data '{"auto_deploy":true}'. MCP: sevalla_api_update with updateApplicationV3.

Deploy

Trigger deployment (triggerDeploymentV3) deploys the latest commit on the application’s 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 and inProgress while it runs, then success or failed. Poll it every 15 seconds, for up to 30 minutes, until the status is final:

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"

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, oldest line first: the build plan from Verify the deployment, the build and the rollout, which ends with Web has been deployed successfully. When the status is failed, the last lines say why. Without limit, the call returns the latest 1,000 lines, so a longer log loses its start; 5000 is the most it allows.

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'

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 domain. Request the home page from it:

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/ | grep -o '<title>[^<]*</title>'

<title>Storefront</title>

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

Build from the Dockerfile with the API

After you push the Dockerfile from Deploy with a Dockerfile, Update application (updateApplicationV3) switches the build strategy. Then repeat the Deploy, Wait for the deployment and Check the application steps:

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":"."}

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

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java, Kotlin and Scala

.NET

Elixir

Gleam

Swift

Dart

Static site generators

Deploy a Remix application

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Deploy changes

Store sessions and files outside the instance

Deploy a React Router application

Deploy with a Dockerfile

Use a Dockerfile for React Router

Add a custom domain

Connect a database

Deploy with the API

Build from the Dockerfile 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 changes

​Store sessions and files outside the instance

​Deploy a React Router application

​Deploy with a Dockerfile

​Use a Dockerfile for React Router

​Add a custom domain

​Connect a database

​Deploy with the API

​Build from the Dockerfile 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 changes

Store sessions and files outside the instance

Deploy a React Router application

Deploy with a Dockerfile

Use a Dockerfile for React Router

Add a custom domain

Connect a database

Deploy with the API

Build from the Dockerfile with the API