DEV Community

Cover image for I turned my whole server into a YAML file, and every change gets a diff first
Known Developer
Known Developer

Posted on

I turned my whole server into a YAML file, and every change gets a diff first

I turned my whole server into a YAML file, and every change gets a diff first

Last month I added a domain to an app at midnight, clicked through three dashboard pages, and could not tell the next morning which of my changes had caused a restart. The server worked. I just had no record of why it looked the way it did.

I tried the other way: write down what the server should look like, ask the control plane what would change, and only then apply it. Levelrail calls this platform as code. Here is what I ran, with the real output, on a throwaway local instance.

TL;DR

Step Command What you get
Preview levelrail-cli apply -f infra/ --dry-run --exit-code A field level plan, exit code 2 if anything would change
Apply levelrail-cli apply -f infra/ --source infra-repo --yes Resources created in dependency order
Check drift levelrail-cli diff -f infra/ --source infra-repo Exit code 2 when live state differs from the files
Capture levelrail-cli export --project shop -o infra/ Existing projects and apps written as YAML

One caveat up front. The docs label this feature experimental, and it ships off. You turn it on with APP_EXPERIMENTAL=iac on the control plane and in the shell where you run the CLI. I used that flag for everything below.

The files

A file holds one or more YAML documents separated by ---. Each has version: 1, a kind (Project, Environment, Tag, Database, App, Domain, LoadBalancer, Pipeline or AlertRule), a name and a spec. This is the whole file I used, a project with an environment, a Postgres database and one app:

version: 1
kind: Project
metadata: { name: w2f-shop }
---
version: 1
kind: Environment
metadata: { name: production }
spec:
  project: w2f-shop
---
version: 1
kind: Database
metadata: { name: w2f-main-db }
spec:
  engine: postgres
  version: "16"
  project: w2f-shop
---
version: 1
kind: App
metadata: { name: w2f-web }
spec:
  project: w2f-shop
  environment: production
  service:
    build: { type: image, image: "traefik/whoami:v1.10.3" }
    port: 80
    domains: [w2f-web.localhost]
    env:
      LOG_LEVEL: info
      DATABASE_URL: { from: { database: w2f-main-db, field: url } }
Enter fullscreen mode Exit fullscreen mode

Two details are worth knowing. The DATABASE_URL line is a reference, not a value. The docs say apply never reads the connection string, so the file, the plan and the stored revisions only ever hold w2f-main-db.url. And documents never contain secret values: the CLI rejects a literal on a key that looks like a password or token, and you point at a secret by name with secretRef.

Apply manages apps that run a prebuilt image. For git builds, use a git source instead of these files.

1. The dry run

levelrail-cli apply -f infra/ --source infra-repo --dry-run --exit-code
Enter fullscreen mode Exit fullscreen mode

This is the real output from my run:

Plan: 4 to create, 0 to update, 0 to delete, 0 unchanged

+ Project/w2f-shop  (infra/shop.yaml:1)
+ Environment/w2f-shop/production  (infra/shop.yaml:5)
+ Database/w2f-main-db  (infra/shop.yaml:11)
    + engine: postgres
    + project: w2f-shop
    + version: 16
+ App/w2f-web  (infra/shop.yaml:19)
    + bindAddress: private
    + connections.DATABASE_URL: w2f-main-db.url
    + domains[w2f-web.localhost]: w2f-web.localhost
    + env.LOG_LEVEL: (hidden)
    + image: traefik/whoami:v1.10.3
    + port: 80
    ...
Enter fullscreen mode Exit fullscreen mode

The exit code was 2, which the docs define as "changes are pending". Zero means nothing to do, and 1 means an error such as invalid files or an unreachable server. That is the whole contract a CI job needs.

The CLI validates everything before it plans anything. If one document has an issue, it plans and applies nothing. Errors carry a file and line. The plan lists the database because the app references it, and databases always go in before apps.

2. Apply

levelrail-cli apply -f infra/ --source infra-repo --yes
Enter fullscreen mode Exit fullscreen mode
applied  Project/w2f-shop
applied  Environment/w2f-shop/production
applied  Database/w2f-main-db
applied  App/w2f-web

4 applied, 0 failed, 0 skipped
Enter fullscreen mode Exit fullscreen mode

I then curled the app through the local ingress with its Host header and got the whoami container's reply. A second diff printed 0 to create, 0 to update, 0 to delete, 4 unchanged and exited 0. The --source flag matters later: it tags what the files created (managed-by:infra-repo) so that pruning can find only those apps.

3. A change, and the diff before it lands

I edited the file: a second domain, a memory and CPU limit, and a different LOG_LEVEL. Then I asked what that would do:

levelrail-cli diff -f infra/ --source infra-repo
Enter fullscreen mode Exit fullscreen mode
Plan: 0 to create, 0 to update, 0 to delete, 3 unchanged

~ App/w2f-web  (infra/shop.yaml:19)
    + domains[shop.localhost]: shop.localhost
    ~ env.LOG_LEVEL: (hidden) -> (hidden)
    + resources.cpu: 0.25
    + resources.memory: 128Mi
Enter fullscreen mode Exit fullscreen mode

Exit 2 again. Env values print as (hidden) on purpose, so you see that a variable changed but never its value. In a pull request review that is a fair tradeoff, and you read the file for the actual value.

This is the moment I wanted at midnight. One app, four fields, nothing else touched. I applied it, and the next diff was clean.

4. Drift

Then I did the thing I used to do by accident. I scaled the app by hand:

levelrail-cli apps scale w2f-web --replicas 2
levelrail-cli diff -f infra/ --source infra-repo
Enter fullscreen mode Exit fullscreen mode
~ App/w2f-web  (infra/shop.yaml:19)
    ~ replicas: 2 -> 1
Enter fullscreen mode Exit fullscreen mode

The plan says live is 2 and the files say 1, exit code 2. The docs suggest running diff on a schedule to catch hand edits. That gives you a cron job that fails when someone has clicked something.

One thing to keep in mind from the docs. Lists and maps on an app (domains, tags, env, labels) are additive, so the plan keeps entries the files do not mention and shows them as keep. Everything else on a declared resource is authoritative.

5. From CI

The docs describe a Git workflow with no sync engine to run. The files live in a repository, the pull request shows the plan, and the merge applies it. I did not run this in GitHub Actions, so treat it as the documented shape and not something I tested. The plan job only needs a read token:

- name: Plan
  env:
    APP_API_URL: ${{ secrets.LEVELRAIL_API_URL }}
    APP_API_TOKEN: ${{ secrets.LEVELRAIL_READ_TOKEN }}
  run: levelrail-cli apply -f infra/ --source infra-repo --dry-run --exit-code || [ $? -eq 2 ]
Enter fullscreen mode Exit fullscreen mode

The apply job on push to main uses a separate write token and --yes. The || [ $? -eq 2 ] is there because exit code 2 means "changes pending", which on a pull request is normal, not a failure.

The plan also carries a hash. The CLI, dashboard and MCP pass it back so an apply only proceeds if live state still matches the plan you reviewed. That makes "reviewed plan, then apply" mean something.

How it compares to the other ways I managed this

Approach Record of changes Preview before change Catches hand edits
Dashboard clicks Whatever the audit trail shows No No
Shell script of CLI calls The script, if you keep it Only if you write one No
apply on YAML files Git history Yes, a field level plan Yes, with diff

The honest limits, taken from the docs: backup schedules, egress policies, node placement, registry credentials and vault env references have no YAML form yet. A live app that uses them keeps them when you apply, and the plan warns. Databases get extra care: apply refuses to change engine or version, because databases hold data.

FAQ

Do I need Kubernetes or a separate GitOps controller for this?

No. It goes through the ordinary REST API with your own token, and the CLI computes and runs the plan. No operator runs in a cluster.

Can I start from an existing server instead of writing YAML?

The docs describe levelrail-cli export --project shop -o infra/, which writes projects and apps as documents and is stable enough that export, apply, export gives identical files. I did not run export on my throwaway instance, so I am relaying the docs here, not my own test.

Will --prune delete things I made by hand?

Per the docs, prune requires --source NAME and only deletes apps carrying that source's tag. Projects, environments, databases, pipelines and alert rules are never pruned.

Is there an API beyond the CLI?

Yes. The docs describe a server-side apply route for apps and databases (PATCH /api/v2/apps/{name} with a field manager and a dry run option) so more than one tool can own different fields. I only read that page.

The bottom line

The feature is small: write YAML, get a plan, get an exit code. What it changed for me is that every change to the server has a diff in front of it, and drift has a command that fails. The next thing I want to measure is how long a pull request plan takes against a server with 30 apps.

If this saved you time, a star on the repo helps others find it.

GitHub logo glincker / levelrail

Self-hosted alternative to Vercel and Coolify. Git push, HTTPS, logs, rollback. No Kubernetes.

Levelrail logo

Levelrail

Your own Vercel, on your own servers.
Push to deploy with HTTPS, logs, metrics and one-step rollback. One Go binary, no Kubernetes. Apache 2.0.

GitHub stars License: Apache 2.0 Latest release CI status Last commit levelrail-cli on npm MCP server Discord

Website · Docs · Install · Compare · FAQ · Roadmap · Discussions

English · 简体中文 · Español · Português (BR) · Deutsch · Français · 日本語

Levelrail: your own Vercel, on your server. The lightweight, self-hosted alternative to Vercel, Heroku and Coolify.

Turn any Linux server into a private cloud: Git deploys, HTTPS, databases with verified backups, metrics, logs and alerts, without Kubernetes and without a monitoring stack to bolt on. Pre-1.0: single-server is production ready, multi-node is beta (Feature status).

Levelrail dashboard tour: fleet overview, apps list, deploy history and built-in metrics










200 MB

idle RAM, 1.5% of one CPU
measured, method included

1 binary

Go control plane, Docker runtime
no Kubernetes

360

one-click service templates
smoke-tested

240+

MCP tools for coding agents
scoped, read-only by default

Install

curl -fsSL https://levelrail.com/install.sh | sudo sh
Enter fullscreen mode Exit fullscreen mode

Needs Linux (amd64 or arm64) with systemd and root; the installer adds Docker. Open ports…




Sources checked

Levelrail docs and code, read at the v1.0.1 release branch: docs/platform-as-code.md, docs/server-side-apply.md, docs/local-development.md, docs/cli-reference.md. All command output above is from a local instance I started with levelrail-cli dev, built from that branch.

Top comments (1)

Collapse
 
ivannovazzi profile image
Ivan Annovazzi •

The drift diff is the part I'd live in, catching stuff you clicked in by hand months ago and forgot about. Question on the YAML files though, where do env vars and secrets go? Inline in a git-tracked file feels wrong for anything sensitive, so I'm guessing references, curious how that looks in practice