Deploy a Gatsby site

A Gatsby site builds to static files: gatsby build renders every page to HTML in the public folder, with the JavaScript that makes it interactive in the browser. Sevalla publishes that folder as a static site, served from Cloudflare’s edge and free up to 100 GB of bandwidth a month. When the site has to run as an application instead, Ingot, Sevalla’s builder, builds it and serves public with Caddy.

At a glance


Source	A Git repository
Build	Static site: `npm run build` on Node 22, publishing `public`. Application: Ingot (Node.js 24, npm, Caddy), or the Dockerfile
Start command	Application: none to set. Caddy serves `public`; Ingot doesn’t run the `start` script, `gatsby develop`
Port	Application: the `PORT` environment variable, `8080` by default
Processes	Application: web process
Disk	None
Size	Static site: none to choose. Application: H1 for the web process

Environment variables

The site needs no environment variables, as a static site or as an application.

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 on your computer. Gatsby 5 runs on Node.js 18 to 25.

Create the project

Create a site from Gatsby’s minimal TypeScript starter, in a terminal:

npx create-gatsby@latest -y -ts storefront
cd storefront

-y accepts the defaults (no CMS, no styling, no plugins) and -ts picks TypeScript. The site comes with a .gitignore, a home page and a 404 page in src/pages, and a build script that runs gatsby build. In gatsby-config.ts, set siteMetadata.siteUrl to the address the site will have, such as https://www.example.com: plugins such as the sitemap read it, and the build doesn’t need it to be right.

Prepare the project for Sevalla

create-gatsby installs the packages with --legacy-peer-deps, so the package-lock.json it writes lacks packages that a plain npm ci expects, and Ingot and the Dockerfile both install with npm ci. Bring the lock file in line, and pin the Node.js version for Ingot:

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

File	Why Sevalla needs it
`package-lock.json`	`npm ci` installs exactly what it lists. After `npm install`, it lists every package `npm ci` checks for.
`package.json` `engines.node`	Ingot builds on the Node.js line it names. Without it, Ingot picks its default line, Node.js 24 today, which a new Ingot release can move. See Pin the Node.js version.

Run npm run build && npm run serve and open http://localhost:9000 to check the build locally. Then commit everything and push it to your Git provider:

git add .
git commit -m "Create the storefront site"
git branch -M main
git remote add origin https://github.com/acme/storefront.git
git push -u origin main

Deploy as a static site

Choose the repository

In the sidebar, click Static sites, then click Create static site. Under Source, click Private repository, then choose the Git provider, the Repository and the Branch.

Set the build settings

Under Build settings, Sevalla shows Framework detected: Gatsby and fills in npm run build and public. Gatsby 5 doesn’t support Node.js 26, the current Latest LTS, so change the Node version:

Field	Value
Build site before publishing	On
Node version	Node 22
Build command	`npm run build`
Root directory	Empty, for the repository root
Publish directory	`public`

Create the static site

Enter a Name under Details, then click Create static site. Sevalla starts the first deployment right away, and deploys every push to the branch while Auto-deploy is on.

Static sites don’t read engines in package.json: the build uses the Node version from the build settings, and npm only warns that 24.x doesn’t match. See Build settings for every field.

Verify the static site

On the Deployments tab, wait for the deployment’s status to change to Deployed. The site’s Status on the Overview tab changes to Live.
On the Overview tab, click Visit site. The starter’s home page opens on its *.sevalla.page domain.

From a terminal, with your site’s domain:

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

<title data-gatsby-head="true">Home Page</title>

With the API, Get static site deployment returns the deployment’s status; see Deploy with the API.

The static site's Details card with its domain, Live status, source repository and the Visit site button

A path with no page returns Sevalla’s 404 page. To show Gatsby’s own 404.html instead, see Custom 404 pages. If the deployment fails, open it on the Deployments tab and read its build log, then see Troubleshoot.

Deploy as an application

An application built from the same repository serves the same files. A static site costs nothing up to the monthly allowances, so use an application only when the site needs something only applications have, such as promoting one build through the stages of a pipeline. Ingot detects Gatsby from package.json, runs the build script and serves the public folder with Caddy. It recognizes the starter’s start script, gatsby develop, as the development server and doesn’t run it. 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 application

On the Deployments tab, click the deployment. Its Build log shows Ingot’s build plan: Gatsby from package.json, built on node:24-trixie and served from an alpine:3 image with Caddy, with no Start row: Caddy serves the files, not the start script.

Build log

╭─ ■ Gatsby · Node.js 24 ──────────────────────────────╮
│ Node.js          24      package.json engines "24.x" │
│ Package manager  npm     package-lock.json           │
│ Framework        Gatsby  package.json                │
├─ Image ──────────────────────────────────────────────┤
│ Build            node:24-trixie                      │
│ Build            caddy:2-alpine                      │
│ Runtime          alpine:3                            │
│ 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 starter’s home page opens. From a terminal:
curl -s https://storefront-x7k2m.sevalla.app/ | grep -o '<title[^>]*>[^<]*</title>' curl -s -o /dev/null -w '%{http_code}\n' https://storefront-x7k2m.sevalla.app/no-such-page
<title data-gatsby-head="true">Home Page</title> 404
With the API, Get deployment returns the deployment’s status and Get application deployment logs its build log; see Deploy with the API.

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

Caddy serves public on the port in PORT, answers missing pages with Gatsby’s 404.html and status 404, and marks the content-hashed files under /static/ as cacheable for a year. To serve them from Cloudflare’s servers, turn on the CDN on the application’s Networking tab. See CDN and edge caching. If the deployment fails, read its build log, then see Troubleshoot and Troubleshoot Ingot builds.

Deploy with a Dockerfile

Ingot needs no Dockerfile. Write one when you want full control of the image: the base image, the web server and every layer. Add a Dockerfile, a Caddyfile 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

FROM caddy:2-alpine AS caddy
RUN setcap -r /usr/bin/caddy

FROM alpine:3
COPY --from=caddy /usr/bin/caddy /usr/bin/caddy
COPY --from=caddy /etc/mime.types /etc/mime.types
COPY Caddyfile /etc/caddy/Caddyfile
COPY --from=build /app/public /srv
ENV XDG_CONFIG_HOME=/tmp XDG_DATA_HOME=/tmp
USER 1000:1000
EXPOSE 8080
CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile", "--adapter", "caddyfile"]

Caddyfile

{
	admin off
	auto_https off
	persist_config off
}

:{$PORT:8080} {
	root * /srv
	encode zstd gzip
	header /static/* Cache-Control "public, max-age=31536000, immutable"
	file_server

	handle_errors 404 {
		rewrite * /404.html
		file_server
	}
}

Line or choice	Why
`node:24-trixie-slim`	Node.js 24, the line `engines.node` pins, on Debian 13, for the build only. A line tag, not a digest, so each build picks up Node.js and Debian security fixes.
Three stages	The `build` stage runs `gatsby build`. The `caddy` stage takes Caddy from its official image and removes the file capability that lets it bind ports below 1024, which a server running as a regular user on port 8080 doesn’t need. The final image is Alpine Linux with Caddy and the site: no Node.js, no `node_modules` and no source.
`package.json` and `package-lock.json` before the source	`npm ci` installs exactly what the lock file lists, and the build cache reuses that layer until the lock file changes, so a change to a page doesn’t reinstall the dependencies.
`handle_errors 404`	Answers missing pages with Gatsby’s `404.html` and status `404`.
`USER 1000:1000`	Caddy runs as a regular user, not root. The copied files stay owned by root, so the server can read them but not change them. Caddy keeps its state in `/tmp`, which `XDG_CONFIG_HOME` and `XDG_DATA_HOME` point to.
`:{$PORT:8080}`	Caddy listens on `PORT`, which Sevalla sets to the web process’s port, or `8080` when it isn’t set. Caddy stops gracefully on `SIGTERM` by itself, so the image needs no init process.

.dockerignore

.git
.cache
node_modules
public
.env*
*.log
Dockerfile
.dockerignore

Commit and push the three files. Ingot doesn’t use the Dockerfile and adds your .dockerignore patterns to its own, so you can keep the 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 domain opens the starter’s home page, and the commands in Verify the application print the same output. See Dockerfile for build arguments and private base images.

Deploy changes

With Auto-deploy on, every push to the branch starts a deployment of the static site or the application; otherwise, deploy each change from the Deployments tab. See Static site deployments and Deployments.

Add a custom domain

To serve the site from your own domain, such as www.example.com, add the domain on the static site’s Domains tab and create the DNS records that Sevalla shows, then set siteMetadata.siteUrl in gatsby-config.ts to it. Applications have a Domains tab too, but custom domains need a web process larger than H1. See Custom domains.

Troubleshoot

Symptom	Cause	Fix
`create-gatsby` stops with `TypeError: Br.cursorTo is not a function`	It draws a progress spinner and needs an interactive terminal; a script or an agent’s shell has none	Run the command in a terminal
An Ingot or Dockerfile build fails at `npm ci` with `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing., then lines such as `Missing: @typescript-eslint/parser@4.33.0 from lock file`	The lock file is the one `create-gatsby` wrote with `--legacy-peer-deps`	Run `npm install`, then commit and push `package-lock.json`, as in Prepare the project for Sevalla
The static site’s build log shows `npm warn EBADENGINE Unsupported engine` for `gatsby@5.16.1`, with `required: { node: '>=18.0.0 <26' }` and `current: { node: 'v26.13.0' }`	The Node version is Latest LTS, Node.js 26, which Gatsby 5 doesn’t support. The build still runs, on a version Gatsby isn’t tested with	Change the Node version to Node 22 in the build settings and deploy again

For more causes, see Troubleshoot static sites and Troubleshoot Ingot builds.

Deploy with the API

This sequence creates the static site from Deploy as a static site and the application from Deploy as an application through the Sevalla API, so an agent or a script can run it as is. Run the first four steps for the static site, the rest for the application. Each step names the operation, shows the curl command, and gives the matching CLI command and MCP server tool. You need:

An API key with the Company developer role, in the SEVALLA_API_KEY environment variable. The CLI reads the same key from SEVALLA_API_TOKEN.
curl and jq, and the project pushed to GitHub as in Prepare the project for Sevalla.
A GitHub account that can read the repository, connected to Sevalla. See Git providers. The API can’t list connected accounts: when none can read the repository, Create static site and Create application fail with 400 and Cannot access repository https://github.com/acme/storefront: Repository not found or you don't have access.

A call that fails returns status and message instead of the resource, and jq -r .id prints null: stop and read the message.

Create the static site

Create static site (createStaticSiteV3) takes the build settings: node_version 22 is the dashboard’s Node 22, and published_directory is the Publish directory.

SITE_ID=$(curl -s https://api.sevalla.com/v3/static-sites \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON | jq -r .id
{
  "display_name": "storefront-web",
  "source": "privateGit",
  "git_type": "github",
  "repo_url": "https://github.com/acme/storefront",
  "default_branch": "main",
  "build_command": "npm run build",
  "published_directory": "public",
  "node_version": "22",
  "auto_deploy": true
}
JSON
)

CLI:

sevalla static-sites create --name storefront-web --repository https://github.com/acme/storefront --branch main --source privateGit --git-type github --build-command "npm run build" --publish-directory public --node-version 22

. MCP: create_static_site with the same fields.

Deploy the static site

Deploy static site (deployStaticSiteV3) starts the first deployment. Unlike the dashboard, creating a static site through the API doesn’t start one.

SITE_DEPLOYMENT_ID=$(curl -s https://api.sevalla.com/v3/static-sites/$SITE_ID/deployments \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r .id)

CLI: sevalla static-sites deployments trigger "$SITE_ID". MCP: trigger_deployment with service_type static_site.

Wait for the static site deployment

Get static site deployment (getStaticSiteDeploymentV3) returns the deployment’s status: waiting, then inProgress, then success or failed. The loop polls every 15 seconds for up to 30 minutes and keeps polling through a failed request.

for i in $(seq 1 120); do
  STATUS=$(curl -s "https://api.sevalla.com/v3/static-sites/$SITE_ID/deployments/$SITE_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"

If it’s failed, Get static site deployment logs (getStaticSiteDeploymentLogsV3) returns the build log. CLI: sevalla static-sites deployments get "$SITE_DEPLOYMENT_ID" --site-id "$SITE_ID" and sevalla static-sites deployments logs "$SITE_DEPLOYMENT_ID" --site-id "$SITE_ID". MCP: get_deployment and get_deployment_logs with service_type static_site.

Check the static site

Get static site (getStaticSiteV3) returns the site’s domain in hostname. Right after a deployment reports success, Cloudflare’s edge can answer with Sevalla’s 404 page for a short time, so the loop waits up to 2 minutes for 200 before the check:

SITE_URL=https://$(curl -s https://api.sevalla.com/v3/static-sites/$SITE_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r .hostname)
for i in $(seq 1 12); do
  [ "$(curl -s -o /dev/null -w '%{http_code}' $SITE_URL/)" = 200 ] && break
  sleep 10
done
curl -s $SITE_URL/ | grep -o '<title[^>]*>[^<]*</title>'

<title data-gatsby-head="true">Home Page</title>

CLI: sevalla static-sites get "$SITE_ID". MCP: get_static_site.

Look up the location and the size

List clusters (listClustersV3) returns every location your company can use, with its region ID. This guide uses Frankfurt, Germany, eu-frankfurt-1. List process resource types (listProcessResourceTypesV3) returns the process sizes.

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

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

Create the application

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

APP_ID=$(curl -s https://api.sevalla.com/v3/applications \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON | 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"
}
JSON
)

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.

Size the web process

The API creates the web process at S1, while the dashboard creates it at H1, which is enough for Caddy. List processes (listProcessesV3) returns the web process, and Update process (updateProcessV3) sets its size. Keep S1, and skip this step, to add a custom domain later.

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

Choose the Dockerfile build strategy (optional)

To build from the Dockerfile in Deploy with a Dockerfile instead of with Ingot, 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

CLI: sevalla apps update "$APP_ID" --data with the same body. MCP: sevalla_api_update with updateApplicationV3 and the same body.

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

true

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

Deploy

Trigger deployment (triggerDeploymentV3) builds the latest commit of the branch and rolls it out.

DEPLOYMENT_ID=$(curl -s 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, then inProgress, then success or failed. The loop polls every 15 seconds for up to 30 minutes and keeps polling through a failed request.

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

CLI: sevalla apps deployments get "$DEPLOYMENT_ID" --app-id "$APP_ID". MCP: get_deployment.

Check the application

Get application deployment logs (getApplicationDeploymentLogsV3) returns the build log, which starts with the build plan in Verify the application and, on a failed deployment, ends with the error. List application domains (listApplicationDomainsV3) returns the application’s domain. Right after a deployment reports success, the domain can answer 503 for a few seconds while traffic moves to the new instance, so the loop waits up to 1 minute for 200 before the checks:

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'
APP_URL=https://$(curl -s https://api.sevalla.com/v3/applications/$APP_ID/domains \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.data[] | select(.is_primary) | .name')
for i in $(seq 1 12); do
  [ "$(curl -s -o /dev/null -w '%{http_code}' $APP_URL/)" = 200 ] && break
  sleep 5
done
curl -s $APP_URL/ | grep -o '<title[^>]*>[^<]*</title>'
curl -s -o /dev/null -w '%{http_code}\n' $APP_URL/no-such-page

After the build log, the output is the same title as for the static site, then 404 from Caddy for a missing page.CLI: sevalla apps deployments logs "$DEPLOYMENT_ID" --app-id "$APP_ID" and sevalla apps domains list --app-id "$APP_ID". MCP: get_deployment_logs and get_application.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java, Kotlin and Scala

.NET

Elixir

Gleam

Swift

Dart

Static site generators

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy as a static site

Verify the static site

Deploy as an application

Verify the application

Deploy with a Dockerfile

Deploy changes

Add a custom domain

Troubleshoot

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Create the project

​Prepare the project for Sevalla

​Deploy as a static site

​Verify the static site

​Deploy as an application

​Verify the application

​Deploy with a Dockerfile

​Deploy changes

​Add a custom domain

​Troubleshoot

​Deploy with the API

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy as a static site

Verify the static site

Deploy as an application

Verify the application

Deploy with a Dockerfile

Deploy changes

Add a custom domain

Troubleshoot

Deploy with the API