Your first app

An app is a container that Velrix keeps running for you. You give it an image and a size; Velrix places it on the server with the most room, starts it, and starts it again if it stops. In this guide you deploy a small web server and look around.

You need an account on a Velrix installation with permission to run apps: your own, or an organisation’s where your role allows it.

1. Open Apps

Sign in, then open Apps from the start menu or the desktop. An installation with no apps yet says No apps yet.

2. Deploy an app

Choose New app. The form has a few tabs; for a first app, only the first one matters.

1. Name: web.
2. Image: a full reference, with its registry. For example:

   docker.io/library/nginx:1.27
   

   
   A short name such as nginx is refused: Velrix always pulls from the registry you name.
3. Size: pick one from your catalogue, such as g.nano. Sizes are your operator’s: each has a family (g general, c compute, m memory) and a name. Custom lets you give your own memory and CPU, in cores.
4. Leave Command empty to run the image’s own command.

Choose Deploy.

When you work in an organisation that has projects, a Project tab lets you put the app in one. Apps in the same project share a private network.

Or start from a blueprint. Library in the start menu holds ready-made apps (nginx, PostgreSQL, Gitea and more) with a pinned image and a sensible size. Choose Deploy on one, and the same form opens filled in.

3. Watch it start

The form closes, and the app is listed in Apps: open it there. Its status goes from Starting to Running, with the server it runs on. The Overview tab shows its CPU and memory in use against what its size gives it, measured every ten seconds.

If something is wrong, the page says so in words:

• No host: no server has room for this size right now. Pick a smaller size, or ask your operator.
• It could not be started: the server could not make it. Check the image name, and that the server can pull it.
• Crashing: it stops right after it starts. The page shows the last exit code, and Velrix tries again, each time a little later, up to every five minutes.

4. Read its logs, open a terminal

• Logs shows the last lines the app wrote to its output. Copy the lines copies them.
• Open a terminal gives you a shell inside the running container, in a window of its own.

5. Tell running from working

Running is not the same as working. A health check is a command Velrix runs inside the container on a timer; exit code 0 means healthy.

On the Health tab, choose Add a check, and for this web server enter:

wget -q -O /dev/null http://127.0.0.1/

Then set how often it runs, how many failures in a row mark it Unhealthy, and whether Velrix restarts it then. The image must contain the tool the command calls: here wget.

6. Give it a disk

An app’s own files go when it is deleted. Data that must stay goes on a volume.

1. Open Volumes and make a volume, with a name and a size. Velrix enforces the size.
2. Back on the app, open the Volumes tab, choose the volume and a Mount path inside the app, such as /usr/share/nginx/html, and choose Attach.

7. Variables and secrets

The Environment on the Run tab holds the variables the app starts with. Seal the ones that are secrets: a sealed value is encrypted, never shown again, and only the container sees it. Saving changes recreates the app.

Clean up

Delete on the app’s page removes the container for good. Its volumes stay, detached, with what is on them.

The same app, as code

Everything above is also an API call. With an API key (the API reference is in your realm’s Docs window):

curl https://velrix.example.com/v1/compute/app.create \
  -H "Authorization: Bearer $VELRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "web", "image": "docker.io/library/nginx:1.27", "size": "g.nano"}'

Or with the OpenTofu and Terraform provider, documented in your realm’s Docs window:

resource "velrix_app" "web" {
  name       = "web"
  image      = "docker.io/library/nginx:1.27"
  memory_mib = 128
}

Next

• Your first VM
• Stacks: OpenTofu with approvals