Node.js hosting with Git deploy

A Node.js site on VeloxaHost is its own container. Setup installs Node.js 22, runs your app as a system service, and puts the Caddy web server in front of it with a free Let's Encrypt certificate. You push code to Git; the console pulls it, installs your dependencies and restarts the app.

Deploy from Git

1. In the console, open Websites and click Add Website.

2. Enter your domain. Under Hosting type, pick Node.js.

3. Optionally set a Start Command. If you leave it empty, the app starts with npm start. It runs from /opt/app and must listen on the port in the PORT environment variable, which is 3000. Caddy forwards your domain to that port.

4. Click Create Website. Setup takes a few minutes and serves a placeholder app until your first deploy.

5. On the site's page, add the DNS records shown under DNS — point your domain here: an A record for the domain and for www, and a TXT record that proves the domain is yours. HTTPS is issued once they resolve.

6. In the Deploy from Git card, click Deploy and fill in:

   • Repository URL (https): a public repository, for example https://github.com/you/app.git.
   • Branch: main unless you say otherwise.
   • Subdirectory: optional. Set it when the app lives in a folder of a larger repository.
   • Auto-deploy: Manual / webhook only, Every hour or Every day.

7. Click Deploy Now. The deploy runs in the background:

   • a shallow clone of the branch;
   • the contents of /opt/app are replaced with the repository (or the subdirectory), keeping node_modules;
   • npm ci if the repository has a package-lock.json, otherwise npm install;
   • a restart of the app.

   Refresh the page to see the result under Recent deploys.

8. To deploy on every push, copy the CI Webhook URL that appears in the card after you save. A POST to it queues a deploy of the saved branch, for example from a GitHub Actions step: curl -fsS -X POST "$VELOXAHOST_DEPLOY_HOOK". The URL contains the site's secret token, so keep it in your CI secrets. Only one deploy runs per site at a time; a webhook call during a running deploy gets a 409 answer.

Build steps

The deploy does not run npm run build. If your app needs a build (Next.js, NestJS, TypeScript), add a prestart script to package.json, such as "prestart": "npm run build". npm runs it before npm start, so the build happens on every restart, including the one after each deploy. The deploy runs a plain npm ci or npm install, so devDependencies such as your compiler are installed. The other option is to commit the built output.

Do not build by hand in the console and expect it to last: each deploy removes everything in /opt/app that is not in your repository, apart from node_modules.

Supported versions

Runtime	Version	Where it comes from
Node.js	22	NodeSource's 22.x package repository, installed during setup

Node.js 22 is the only version a Node.js site sets up. There is no version picker. If you need another Node.js major, a VPS gives you full control of the runtime.

FAQ

Which port should my app listen on?

The port in the PORT environment variable, which is 3000. Caddy forwards your domain to 127.0.0.1:3000 and handles HTTPS, so your app speaks plain HTTP.

Does a deploy run my build script?

No. A deploy installs dependencies with npm ci (or npm install when there is no lockfile) and restarts the app. Add a prestart script that runs your build, or commit the built files.

How do I set environment variables and secrets?

The console has no environment variable form yet, and a deploy removes files in /opt/app that are not in your repository. Open the site's console (Advanced > Open Console, a root shell in the container) and add an override to the app's service with systemctl edit veloxa-app, for example Environment=DATABASE_URL=... under [Service]. Then run systemctl restart veloxa-app.

Can I change the start command after the site is created?

The start command is written into the veloxa-app service when the site is set up. The simple way to change what runs is the start script in your package.json, because the default command is npm start. You can also edit the service from the console.

Can I deploy a private repository?

The Git deploy clones a public repository over https. It does not store Git credentials or deploy keys for sites.

Does a Node.js site include a database?

No. The MariaDB server comes with Classic hosting (PHP sites). Connect a Node.js app to a database you run elsewhere, for example on a VPS.