Skip to main content
A Next.js application runs on Sevalla as an application: Ingot, Sevalla’s builder, detects Next.js in your Git repository, runs next build, and the web process runs next start, the Next.js server, which supports every Next.js feature. A site that needs no server can instead be exported to static files and published as a static site.

At a glance

Environment variables

Neither the application nor the static export needs environment variables of its own. Sevalla sets PORT to the application’s web process port. Variables that start with NEXT_PUBLIC_ must be available during the build: see Use 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

Create a project with the default options (TypeScript, Tailwind CSS, ESLint and the App Router):
The project comes with a .gitignore, a Git repository and the scripts Ingot uses: build runs next build and start runs next start.

Prepare the project for Sevalla

Pin the Node.js version:
Without it, Ingot builds on its default line, Node.js 24 today, which a new Ingot release can move. See Pin the Node.js version. Nothing else needs to change. Ingot installs the dependencies with npm ci, runs the build script, removes the devDependencies, such as Tailwind CSS and TypeScript, which next start doesn’t need, and starts the web process with the start script. next start takes its port from PORT, which Sevalla sets to the web process’s port (8080 by default), and listens on all network interfaces. Run npm run build && npm start and open http://localhost:3000 to check the production build locally. Then commit everything and push it to your Git provider:

Deploy to Sevalla

These steps build with Ingot. To build from your own Dockerfile instead, see 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.

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, Next.js from package.json, and next start from the start script.
    Build log
  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 Next.js starter page opens.
  4. Check the page’s title from a terminal:
The application header with its name, Running status, repository, branch and the domain that opens the applicationThe 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 it deploys but the domain doesn’t respond, 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.

Use environment variables

Add configuration on the application’s Environment variables tab. Next.js reads server-side variables at runtime, but it writes variables that start with NEXT_PUBLIC_ into the JavaScript bundle during next build, so keep Available during buildtime selected for them and deploy again after you change one. See Environment variables during the build.

Cache pages and assets

Next.js gives the files under /_next/static/ content hashes, so they’re safe to cache for a long time. Turn on the CDN on the application’s Networking tab to serve static assets from Cloudflare’s servers, and edge caching to serve rendered pages from there too. Edge caching suits pages that are the same for every visitor. See CDN and edge caching.

Build a standalone server

With output: "standalone", next build writes a server with only the dependencies it uses to .next/standalone. Ingot detects the setting and builds a smaller image: it copies only .next/standalone, .next/static and public into it, instead of the whole project and its node_modules, and starts the web process with node server.js. In next.config.ts, replace the /* config options here */ line with the setting:
next.config.ts
Commit and push the change. In the next deployment’s build plan, the Framework row shows Next.js (standalone) and the Start row shows node server.js. The standalone server reads PORT too, and Ingot sets HOSTNAME to 0.0.0.0 so that it listens on all network interfaces.

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. This one runs the standalone server, so set output: "standalone" first, as in Build a standalone server. Add a Dockerfile and a .dockerignore to the root of the repository:
Dockerfile
.dockerignore
The .dockerignore keeps local builds, installed packages and local environment files out of the image, so it builds from the committed source only. Sevalla passes build-time environment variables to the build as build arguments: to use a NEXT_PUBLIC_ variable, declare it with ARG in the build stage, before RUN npm run build. See Use build arguments. 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:
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 status changes to Deployed, the application’s domain opens the Next.js starter page, and curl -s https://storefront-x7k2m.sevalla.app/ | grep -o '<title>[^<]*</title>' prints <title>Create Next App</title> again. To switch the build strategy with the API, see Build from the Dockerfile with the API.

Deploy a static export

When every page can be built ahead of time, Next.js can export the site to HTML, CSS and JavaScript files, and Sevalla publishes them as a static site, free up to 100 GB of bandwidth a month. A static export doesn’t support features that need a server, such as Server Actions, Proxy (formerly middleware), cookies and Incremental Static Regeneration. See the list of unsupported features. Replace next.config.ts with this:
next.config.ts
Run npm run build to check that it writes the out folder. Commit and push the change, then create the static site:
1

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

Check the build settings

Under Build settings, Sevalla shows Framework detected: Next.js and fills in the values. Check them:
3

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.
When the deployment’s status changes to Deployed, click Visit site on the static site’s Overview tab. The Next.js starter page opens on the site’s *.sevalla.page domain, for example storefront-x7k2m.sevalla.page. From a terminal:
With the API, Get static site deployment (getStaticSiteDeploymentV3) returns the deployment’s status, success once it’s deployed, and Get static site deployment logs (getStaticSiteDeploymentLogsV3) returns its build log, which ends with Static site has been deployed successfully. See Deploy the static export with the API. Static sites don’t read engines.node: the build uses the Node version in the build settings. If the deployment fails, see Troubleshoot static sites. See Build settings for every field.

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. Static sites have a Domains tab too. 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 code with process.env.DB_URL.

Deploy with the API

These calls make the same deployments as Deploy to Sevalla and Deploy a static export, 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 for the application and STATIC_SITE:CREATE, STATIC_SITE:READ and STATIC_SITE:UPDATE for the static site, 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 or the static site 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.

Deploy the application with the API

1

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:
CLI: sevalla resources clusters. MCP: get_platform_options.
2

Find the H1 size

List process resource types (listProcessResourceTypesV3) returns the sizes by name, in lowercase:
CLI: sevalla resources process-types. MCP: get_platform_options.
3

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

Find the web process

List processes (listProcessesV3) returns the web process that the application was created with:
CLI: sevalla apps processes list --app-id $APP_ID. MCP: get_application.
5

Set the size

The API creates the web process at S1, where the dashboard’s default is H1. Update process (updateProcessV3) sets 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.
6

Turn on auto-deploy

Update application (updateApplicationV3) turns on automatic deployments for every push to the branch:
CLI: sevalla apps update $APP_ID --data '{"auto_deploy":true}'. MCP: sevalla_api_update with updateApplicationV3.
7

Deploy

Trigger deployment (triggerDeploymentV3) deploys the latest commit on the application’s branch:
CLI: sevalla apps deployments trigger $APP_ID. MCP: trigger_deployment.
8

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:
CLI: sevalla apps deployments get $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment.
9

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.
CLI: sevalla apps deployments logs $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment_logs.
10

Check the application

List application domains (listApplicationDomainsV3) returns the application’s domain. Request the home page from it:
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 application’s build strategy. Then repeat the application’s Deploy, Wait for the deployment and Check the application steps:
CLI: sevalla apps update $APP_ID --data '{"build_type":"dockerfile","dockerfile_path":"Dockerfile","docker_context":"."}'. MCP: sevalla_api_update with updateApplicationV3.

Deploy the static export with the API

1

Create the static site

Create static site (createStaticSiteV3) creates the static site with the build settings from Deploy a static export. "node_version":"lts" is Latest LTS. Unlike the dashboard, the API turns on auto-deploy only when the body asks for it, and it doesn’t start a deployment:
CLI: sevalla static-sites create --name storefront --source privateGit --git-type github --repository https://github.com/acme/storefront --branch main --build-command "npm run build" --node-version lts --publish-directory out, which leaves auto-deploy off. MCP: create_static_site with the same fields.
2

Deploy

Deploy static site (deployStaticSiteV3) builds and publishes the latest commit on the branch:
CLI: sevalla static-sites deployments trigger $SITE_ID. MCP: trigger_deployment with service_type set to static_site.
3

Wait for the deployment

Get static site deployment (getStaticSiteDeploymentV3) 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:
CLI: sevalla static-sites deployments get $DEPLOYMENT_ID --site-id $SITE_ID. MCP: get_deployment with service_type set to static_site.
4

Read the build log

Get static site deployment logs (getStaticSiteDeploymentLogsV3) returns the build log, oldest line first: the build settings, the install, the build and the upload, which ends with Static site 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.
CLI: sevalla static-sites deployments logs $DEPLOYMENT_ID --site-id $SITE_ID. MCP: get_deployment_logs with service_type set to static_site.
5

Check the site

Get static site (getStaticSiteV3) returns the site’s domain in hostname. Request the home page from it:
CLI: sevalla static-sites get $SITE_ID. MCP: get_static_site.