Deploy an App from Git

Overview

An app is built from a branch of your repository and runs as a web service or a static site. You connect your git provider once, choose the repository, and Cosmoner builds it — either by detecting your stack or by running your Dockerfile — and serves it over HTTPS.

The whole flow is three steps in the control panel: Domain, Application and Configure. Open your project, go to Apps, and select New app.

Before you start

• A project with a payment method. Apps are billed monthly from the plan you choose — see Apps Pricing.
• Your code in a repository on GitHub, GitLab or Bitbucket.
• For a web service: a process that listens for HTTP on the port in the PORT environment variable. Most frameworks already do — see Ports.

Deploying straight from a public repository URL without connecting a provider is not supported. If you would rather not connect one, build an image yourself and deploy it as a container image.

1. Choose a domain

Pick where the app will be reachable:

• Use a free cosmoner.com address. The app gets a generated address such as my-app-3f9a.cosmoner.com at no extra charge, shown once it is deployed.
• Select an existing domain. Any active domain in your project, as the root domain or under a subdomain you name, e.g. app.example.com.

You can switch between the two later, from the app's Network tab with Change public URL. An app has one public address at a time.

2. Choose the repository and how it builds

Under Git Repository, choose your provider and connect your account the first time. GitHub is connected by installing the Cosmoner GitHub App on the account or organization that owns the repository; GitLab and Bitbucket are connected by signing in. Once connected, pick the repository and the Branch to deploy.

If the repository has a .cosmoner/deployment.yaml, the wizard offers Fill in from file — see App Configuration Files. Every setting below can also be filled in by hand.

Source

App directory is the folder the app is built from. Leave it at the root for a single app; for a monorepo, point it at the service, e.g. apps/api.

Build

Choose the app type:

And the build strategy:

Build command and Run command are detected for you with Automatic; set them only to override what was detected, e.g. npm run build and npm run start.

A static site takes an Output directory instead — the folder your build writes the site into, dist by default. Its build command runs in a clean Node.js 22 environment holding your files and nothing else, so install your dependencies as part of it: npm ci && npm run build. A site with nothing to build needs no command; the output directory, or the app directory when none is set, is served as it is.

Ports

A web service is given its port in the PORT environment variable. If your app listens on $PORT, leave Port empty. If it listens on a fixed port instead, the port is chosen in this order:

1. The Port you set.
2. The port in your Dockerfile's EXPOSE, for Dockerfile builds.
3. 8080.

Environment variables

Add what your app needs to run. Each row can be:

• a plain value, with Add variable;
• a stored secret, with Link secret — the value stays in the vault and is read when the app deploys, so rotating the secret needs no change to the app;
• a project variable, with Link variable;
• or several at once, with Import variables from a .env file or pasted text.

Variables are available while the app builds as well as while it runs, so values a framework bakes into the build — NEXT_PUBLIC_*, VITE_* — work. The build log lists variable names, never their values. See Secrets for storing sensitive values.

Deployment

Auto-deploy on push is on by default: every push to the selected branch builds and deploys a new version. Turn it off to deploy only when you ask.

3. Configure and launch

Name the app, then choose:

• Plan — the instance size for a web service: vCPU, memory and a monthly bandwidth allowance for one fixed price. Static sites skip this.
• Region.
• Instances — how many copies of the service run behind the address.

The summary shows the monthly price and what is charged today. Select Launch to start the first build.

After it launches

The app's detail page has everything you need while it runs:

HTTPS is set up for you, on the cosmoner.com address and on custom domains alike.

Redeploying

With auto-deploy on, a push is a deploy. To build the current branch again without pushing, select Redeploy in the app's header.

Changing an environment variable on the General tab saves it, but the running app keeps the old value until the next deploy — redeploy to apply it. The same goes for anything baked in at build time.

Rolling back

The Deployments section of the app's Overview tab lists its recent deployments and marks the one that is running. Any earlier deployment that went live has Roll back, which puts the app back on the image that deployment ran — immediately, without building anything.

Only the code goes back. The app keeps its current environment variables and settings, so if a bad deploy came with a variable change, change that back too. With auto-deploy on, your next push moves the app forward again as usual.

Rolling back is not available while another deployment is in progress. Through the API, it is POST .../deployments/{deploymentId}/rollback.

Using your own domain

Add the domain to your project under Domains first. Then, on the app's Network tab, select Change public URL → Custom domain and choose it. For a domain whose DNS you manage elsewhere, the panel shows a CNAME and a TXT record to add; once they are in place, select Verify now and the certificate is issued.

Troubleshooting

The build fails. Open Build logs. With Automatic, check that the App directory points at the folder containing your package.json, requirements.txt, go.mod or equivalent. With Dockerfile, check that the Dockerfile is in that same folder.

The build succeeds but the deploy never becomes healthy. Almost always a port mismatch: the app is listening on a port other than the one it was given. Make it listen on $PORT, or set Port to the port it uses. A release that has not started serving within ten minutes is marked failed.

A static site answers an unknown path with the wrong page. Paths are served the way static hosts usually do: /about finds about.html or about/index.html, and a path that matches nothing gets your top-level 404.html with a 404 status if the site has one. A site without a 404.html is treated as a single-page app, and every unknown path gets index.html so its router can take over. Add a 404.html for a set of pages; leave it out for a single-page app. A path ending in a file extension, such as a missing .js file, is always a 404.

Next steps

• Deploy a Next.js App
• App Configuration Files — keep these settings in your repository.
• Connect to Redis — add a cache or queue to your app.