go.sum, compiles the main package into a static binary, and the web process runs that binary, /usr/local/bin/storefront. The server listens on the port that Sevalla sets in the PORT environment variable, runs in release mode, and reads the visitor’s IP address from the header Cloudflare sets.
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.
- Go 1.27 on your computer.
Create the project
Create a folder and a Go module, and add Gin. The last part of the module path,storefront, becomes the name of the binary:
go get installs Gin 1.12. The -u flag also updates Gin’s dependencies to their newest releases: Gin 1.12.0 asks for releases of golang.org/x/net, golang.org/x/crypto and golang.org/x/text that have known vulnerabilities.
Create the server, a JSON API with a health endpoint:
main.go
gin.Default()adds Gin’s request logger and its recovery middleware, which turns a panic into a500response.- The router runs in an
http.Serverinstead ofrouter.Run(), so the server can shut down gracefully. See Shut down gracefully. - The server listens on
PORT, which Sevalla sets to the web process’s port (8080by default), on all network interfaces. On your computer, it uses port 8080. TrustedPlatformandSetTrustedProxies(nil)makec.ClientIP()return the visitor’s address. See Get the visitor IP address.
go build writes out of the repository:
.gitignore
Prepare the project for Sevalla
The project needs no build or start configuration:
Nothing in Gin’s dependencies imports
"C", so Ingot builds with CGO_ENABLED=0, and the binary needs no C library at runtime.
Run go run . and open http://localhost:8080/api/products to check the server locally. On your computer, Gin runs in debug mode: it lists its routes and warns about it at start. 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
Add the environment variable
Click the Environment variables tab, then click Add environment variables. Add
GIN_MODE with the value release and click Add environment variables. Gin reads it at start: in release mode, it doesn’t print its debug output.3
Deploy
Click the Overview tab, then click Deploy now under Recent deployments. Check the Branch and click Deploy.
4
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: Go 1.27 from the
goline ofgo.mod, and the start command from themainpackage at the root.Build log - 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, and add/api/productsto the address. The response is:/api/products/2returns one product,/api/products/9returns{"error":"product not found"}with status404,/healthzreturns{"status":"ok"}, and/api/ipreturns your own IP address.


Listening on port 8080, then one line per request with the visitor’s address, and none of Gin’s debug output. If the deployment fails, read its build log, then see Troubleshoot.
To check the deployment from a terminal or an AI agent, read its status with Get deployment (getDeploymentV3) until it’s success, and its build log with Get application deployment logs (getApplicationDeploymentLogsV3), as in Deploy with the API. Then request the endpoints:
getApplicationRuntimeLogsV3) with search finds the start of the server:
Get the visitor IP address
Every request reaches the application through Cloudflare and Sevalla’s proxy, so the connection comes from the proxy, and theX-Forwarded-For header lists the addresses the request passed through, starting with whatever the client itself sent. Gin’s default trusts every proxy and returns the first address in X-Forwarded-For: without the two lines after gin.Default(), a request sent with X-Forwarded-For: 203.0.113.99 gets 203.0.113.99 from c.ClientIP(), and Gin warns You trusted all proxies, this is NOT safe in debug mode.
router.TrustedPlatform = gin.PlatformCloudflaremakesc.ClientIP()return theCF-Connecting-IPheader, the visitor’s address that Cloudflare sets on every request. Cloudflare refuses requests that already carry the header, witherror code: 1000.router.SetTrustedProxies(nil)stops Gin from readingX-Forwarded-For, so a request withoutCF-Connecting-IP, such as one from your computer, gets the connection’s address.
c.ClientIP() too, so the runtime logs show the visitor’s address. See Request headers for every header Sevalla and Cloudflare add.
Shut down gracefully
When Sevalla stops an instance, during a deployment, a restart or a scale-down, it waits 5 seconds, sendsSIGTERM, and stops the instance if it’s still running 30 seconds after the shutdown began. See How processes run.
signal.NotifyContext turns SIGTERM into a cancelled context, and srv.Shutdown stops accepting connections and waits up to 20 seconds for the requests in progress. On every deployment, the old instance’s runtime logs end with Shutting down and Server stopped. Keep the shutdown timeout under 25 seconds.
Add a health check
A readiness probe makes each new instance wait for/healthz to answer before it gets traffic, so a deployment switches over only to instances that serve requests.
1
Open the web process
On the application’s Processes tab, click ⋯ on the Web process, then click Update process.
2
Turn on the readiness probe
Under Health checks, turn on Readiness probe and set the Path to
/healthz. Keep the Port at the web process’s port, 8080 unless you changed it.3
Save and deploy
Click Update process, then click Deploy in the undeployed changes bar at the bottom of the page.
getProcessV3) returns it in readiness_probe:
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 aDockerfile and a .dockerignore to the root of the repository:
Dockerfile
.dockerignore
.dockerignore keeps the Git history, local environment files, logs and a binary you built locally out of the build.
Commit and push both files. Ingot doesn’t build from your Dockerfile, and it adds the patterns in .dockerignore 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.
📦 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, /api/products returns the same JSON. See Dockerfile.
With the API, Update application (updateApplicationV3) switches the build strategy. Then deploy and wait as in Deploy with the API:
sevalla apps update $APP_ID --build-type dockerfile --dockerfile-path Dockerfile. The new deployment’s build log names the Dockerfile build:
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. When you add a module, rungo mod tidy and commit go.mod and go.sum with the code. See Deployments.
Use environment variables
Add configuration on the application’s Environment variables tab and read it withos.Getenv, as the server reads PORT. Variables marked Available during buildtime also reach go mod download and go 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 asshop.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.
Troubleshoot
For more causes, see Troubleshoot Ingot builds and Troubleshoot builds and deployments.
Deploy with the API
These calls make the same deployment as Deploy to Sevalla and Add a health check, 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:READandAPP:UPDATEpermissions, in theSEVALLA_API_KEYenvironment variable. The CLI reads the key fromSEVALLA_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
400withCannot access repository https://github.com/acme/storefront: Repository not found or you don't have access., followed by where to grant access. curlandjq.
1
Choose the location
List clusters (CLI:
listClustersV3) returns the locations your company can use, each with its id, the display_name that the dashboard shows and its region ID in location. Keep the ID of the one you want by its region ID, such as eu-frankfurt-1 for Frankfurt, Germany. Locations lists them all:sevalla resources clusters. MCP: get_platform_options.2
Create the application
Create application (CLI:
createApplicationV3) creates the application with a web process. It builds with Ingot (build_type is ingot) and isn’t deployed yet: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.3
Find the domain
List application domains (CLI:
listApplicationDomainsV3) returns the domain that Sevalla gives the application. It appears a few seconds after the application is created, so ask until it’s there:sevalla apps domains list --app-id $APP_ID. MCP: get_application.4
Add the environment variable
Create environment variable (CLI:
createEnvironmentVariableV3) adds GIN_MODE, available at runtime only. Without is_buildtime, a variable is available during the build too:sevalla apps env-vars create $APP_ID --key GIN_MODE --value release; it always makes a variable available during the build and runtime. MCP: set_environment_variables with buildtime set to false.5
Find the web process
List processes (CLI:
listProcessesV3) returns the web process that the application was created with:sevalla apps processes list --app-id $APP_ID. MCP: get_application.6
Find the H1 size
List process resource types (CLI:
listProcessResourceTypesV3) returns the sizes by name, in lowercase:sevalla resources process-types. MCP: get_platform_options.7
Set the size and the readiness probe
The API creates the web process at S1, where the dashboard’s default is H1. Update process (CLI:
updateProcessV3) sets the size and adds the readiness probe from Add a health check, with the dashboard’s default timings. Send timeoutSeconds: a probe without it gets 120 seconds, where the dashboard sets 1.sevalla apps processes update $WEB_ID --app-id $APP_ID --resource-type $H1_ID sets the size; the CLI can’t set probes. MCP: scale_process with size_id for the size, and sevalla_api_update with updateProcessV3 and the same body for the probe.8
Turn on auto-deploy
Update application (CLI:
updateApplicationV3) turns on automatic deployments for every push to the branch:sevalla apps update $APP_ID --data '{"auto_deploy":true}'. MCP: sevalla_api_update with updateApplicationV3.9
Deploy
Trigger deployment (CLI:
triggerDeploymentV3) deploys the latest commit on the branch:sevalla apps deployments trigger $APP_ID --branch main. MCP: trigger_deployment.10
Wait for the deployment
Get deployment (CLI:
getDeploymentV3) returns the deployment’s status: waiting and inProgress while it runs, then success, failed, cancelled or skipped. Poll it until the status is final, for up to 30 minutes:sevalla apps deployments get $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment.11
Read the build log
Get application deployment logs (CLI:
getApplicationDeploymentLogsV3) returns the build log, oldest line first: the build plan from Verify the deployment, the build and the rollout. When the status is failed, the last lines say why.sevalla apps deployments logs $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment_logs.12
Check the application
Request the products from the application’s domain:Then run the other checks in Verify the deployment.