Migrating from Atelier to Opsting

Atelier is becoming Opsting. This guide covers what changes, and how to move an existing installation across.

This is a rebuild, not an upgrade

There is no in-place upgrade path, and that is deliberate. The rename changes identifiers that Kubernetes uses to find your workloads — the namespace, the resource labels, the API token prefix. Rewriting those under a running cluster risks orphaning live workloads with no error message. Standing up a fresh install and re-onboarding your apps is slower to read about but much safer to do.

Your source code and your app data both come across intact. Nothing is thrown away.

Before you start

Use a second host if you possibly can. Install Opsting alongside your existing Atelier box rather than over it. The old install keeps serving while you verify the new one, and rollback costs nothing — you just keep using the old box. Migrating in place means downtime and no easy way back.

Set aside a couple of hours for a dozen or so apps, most of it waiting on builds.

You do not need to stop your Atelier install to take the backups below. Every step here reads from running pods.

What changes

	Atelier	Opsting
Kubernetes namespaces	atelier, atelier-apps	opsting, opsting-apps
Resource labels	atelier.io/*	opsting.io/*
API token prefix	atl_…	ops_… — existing tokens stop working
Environment variables	ATELIER_*	OPSTING_*
Config files	atelier.toml, atelier-spec.yaml	opsting.toml, opsting-spec.yaml — you must rename the spec in each repo
In-cluster registry	registry.atelier.local	registry.opsting.local
Agent skills	atelier-build, atelier-operate	opsting-build, opsting-operate — agents must reinstall them
Installer binary	atelier-install	opsting-install
MCP server name	atelier (tools mcp__atelier__*)	rename it in your MCP host config

The three that need action on your side rather than the platform’s are the token prefix (re-mint any tokens your agents use), the skills (reinstall under their new names), and app URLs if you change your portal domain.

Step 1 — Preserve your data

Take an independent copy before touching anything, even if you have backups configured. These commands read from the running system.

Your app source

Every app’s source lives in the platform’s Gitea. This is the important one — with the repos you can always rebuild an app.

kubectl exec -n atelier deploy/gitea -- \
  tar czf - -C /data/git repositories > gitea-repos.tar.gz

The platform database

POD=$(kubectl get pods -n atelier -l app=atelier-core -o name | head -1)
kubectl exec -n atelier ${POD#pod/} -c atelier-core -- \
  sh -c 'cd /data && tar czf - atelier.db atelier.db-wal' > atelier-db.tar.gz

Your app data

Copy the -wal file, not just the database

Most apps store data in SQLite, and SQLite in WAL mode keeps recent writes in a separate -wal file until it checkpoints. Copying only app.db can give you a database with no data in it — sometimes not even a schema.

On one real app we measured a 4 KB app.db sitting beside a 457 KB app.db-wal. Everything was in the WAL.

Always copy the whole data directory, or at minimum the database and its -wal.

POD=$(kubectl get pods -n atelier-apps -l atelier.io/app=<app> -o name | head -1)
kubectl exec -n atelier-apps ${POD#pod/} -- \
  sh -c 'cd /data && tar czf - --exclude=lost+found .' > <app>-data.tar.gz

Three things that will bite you here:

• Check the mount path. Not every app mounts at /data. Confirm with kubectl get pod <pod> -o jsonpath='{.spec.containers[*].volumeMounts[*].mountPath}'.
• Some containers have no shell. Minimal or distroless images have no sh, so kubectl exec fails outright. For those, scale the app to 0 and mount the volume in a temporary pod instead.
• tar exits non-zero on a live directory (“file changed as we read it”). The archive is still fine — just don’t chain the next command with &&.

For PostgreSQL apps, use pg_dump. A file copy of a live Postgres data directory is not consistent:

kubectl exec -n atelier-apps <postgres-pod> -- sh -c \
  'PGPASSWORD=$(printenv POSTGRES_PASSWORD) pg_dumpall -h 127.0.0.1 \
   -U $(printenv POSTGRES_USER)' > <app>-postgres.sql

Your secrets and config

kubectl get secrets,configmaps -n atelier-apps -o yaml > app-config.yaml
chmod 600 app-config.yaml

Verify every transfer

Streams can truncate silently

Piping large files out of kubectl exec can drop data with no error at all. We lost 1.2 MB off a 64 MB file this way and only noticed because the checksum disagreed.

Checksum inside the pod, then compare:

# in the pod
kubectl exec ... -- sha256sum /tmp/archive.tar.gz
# locally
sha256sum archive.tar.gz

Step 2 — Install Opsting

Follow the install guide on your new host. Nothing carries over from the old machine — new install, new credentials, new tokens.

Step 3 — Bring your apps back

For each app you want to keep:

1. Create it. Use scaffold, which makes an empty app plus a Git repo with a build-on-push webhook.

Why not “clone from Git”?

The clone on-ramp only accepts https:// URLs on public hosts — it deliberately refuses private-network addresses. It cannot reach your old install’s Gitea, so scaffold-and-push is the route.

2. Rename your spec file, if the app has one.

atelier-spec.yaml is no longer read

If your repo declares services in atelier-spec.yaml, rename it:

git mv atelier-spec.yaml opsting-spec.yaml

Opsting stops the build if it finds the old filename and not the new one, and tells you exactly this. That is deliberate. Silently ignoring the file would not fail — it would fall back to reading your Dockerfiles and deploy a different app than you declared, dropping a companion database, say. A build that stops is recoverable in one command; a wrong deployment that looks fine is not.

Apps with no spec file are unaffected — building from Dockerfiles alone is still normal.

3. Push your archived source into the new app’s repo, authenticating with an Opsting API token as the git password.

4. Push one more commit.

Your first build may not start

Older versions of Atelier committed Kubernetes manifests back into app repos. Those commits are marked as machine-generated, and the platform skips builds for pushes that contain only machine-generated commits — otherwise builds would loop forever.

If your archived repo’s most recent commits are those manifest commits, the first build is skipped silently: no error, no logs, the app just sits there.

An empty commit is enough to fix it:

git commit --allow-empty -m "trigger first build"
git push

5. Wait for it to build, then check the app reports as running.

Apps deployed from a published image (rather than built from source) don’t need any of this — re-import them with the same image reference.

Step 4 — Restore app data

For each app that has data:

# 1. stop the app so nothing is writing
kubectl scale deploy/<app> -n opsting-apps --replicas=0

# 2. restore into the volume (via a temporary pod mounting the PVC)
#    - untar your archive into the mount path
#    - DELETE any stale *-shm file the fresh app created

# 3. start it again
kubectl scale deploy/<app> -n opsting-apps --replicas=1

Delete the stale -shm file

The freshly built app creates its own empty database with -wal and -shm sidecars. Your archive replaces the database and the -wal, but not the -shm — and leaving a mismatched -shm beside a restored database can corrupt it, reporting as database disk image is malformed.

Delete *-shm at the destination before you untar. Never restore into a volume while the app is running.

Step 5 — Finish up

• Re-mint API tokens. The prefix changed, so old tokens are invalid.
• Reinstall the agent skills. They are now opsting-build and opsting-operate. Remove the old ones — an agent holding both will get conflicting instructions, and the old skills describe endpoints and a token prefix that no longer exist.
• Update your MCP host config. If you registered the server as atelier, rename the entry; tools surface as mcp__<server-name>__*, so anything referring to mcp__atelier__* needs to follow.
• Re-point external integrations — webhooks, bots, anything calling into your apps — at the new URLs.
• Update your hosts file or DNS for the new portal domain.

Step 6 — Retire the old install

Keep the old box running until you’re satisfied. There’s no rush, and while it exists you have a complete, working fallback.

Keep your Step 1 archives even after you decommission it.

If you get stuck

Ask on Discord. If you hit something this guide doesn’t cover, tell us — this guide was written from a real migration, and it improves every time someone finds a new edge.