Skip to content

Updates

The desktop app and the server update separately. The desktop app downloads new versions by itself and installs them when you restart it. The server updates when an admin presses Update server, or when you run docker compose pull.

Atelier asks for the newest version when the app starts, after you sign in to a server, and every 5 minutes after that. A check reads one small file. Settings › System › Updates › Check now asks immediately. Changing the Update channel also checks once.

Settings › System (desktop app only) has, under This app:

Row What
Updates The state in words, and the button for what comes next: Check now, Download, Restart to update or Releases page.
Check for updates automatically On by default. Off: the app asks no feed anything by itself, only Check now does.
Update channel Stable or Beta. “Beta gets new versions before they’re released as stable.”
You use The app asks
Connect to a server whose admin set up a feed (Serving desktop updates) The server’s /updates/<channel>/, with your sign-in token (sent to that server only).
Connect to a server with no feed The server answers 404, and the app uses the public feed instead. Without a public feed too, Updates reads “The server doesn’t offer updates for this computer yet. Its admin sets them up with ATELIER_UPDATES_REPO.”
Run on this computer The public feed, https://updates.atelierhq.dev/<channel>/.

The ATELIER_UPDATE_FEED environment variable of the desktop process replaces the public feed’s address with yours, or with off to remove it. With the public feed removed and no server feed, Updates says “This copy has no update source, so it can’t check for new versions. Get them from the Releases page.” and the channel below it is greyed out.

Settings › System › Update channel is a setting of this computer, kept in updates.json in the app’s profile folder.

  • Stable is the default: released versions.
  • Beta gets new versions before they are stable. On Atelier’s public feed that is whatever is published to the beta folder; on a server’s feed it is the newest release including prereleases (a tag containing -, such as v0.3.0-beta.1).
  • Atelier never downgrades. Moving from Beta to Stable while the beta is newer keeps you on the beta until a stable version passes it.
  1. Available. The state reads “Atelier 0.1.10 is available. Downloading…”.
  2. Downloading. The sidebar shows “Downloading Atelier 0.1.10”. Before anything is downloaded, the update’s signature is checked (see What is verified).
  3. Ready. The sidebar shows “Update 0.1.10 is ready” with Restart; Settings says “Atelier 0.1.10 is ready. It installs when you quit Atelier, or restart now.” and offers Restart to update. The update installs when you quit Atelier, or the next time you start it.

While an update waits, the app keeps checking. If a still newer version appears, it is downloaded (after the same checks) and replaces the waiting one, so you never restart into an older update. The same version is never downloaded twice. If the newer download fails, the one that waits stays offered.

The first time you open a new version, a What’s new in Atelier dialog lists what changed: the changes that matter, then the smaller ones, with a link to the full changelog. Larger features come with a short clip of them at work. If you skipped versions, every version since the one you had follows, newest first, each with its own notes (up to eight; the changelog has the rest). It shows once per person and not on a new install. Open it again from More › What’s new in the sidebar: it shows the same versions again. The clips come with the app, so opening the dialog sends nothing anywhere.

How it updates
macOS Downloads the zip for your Mac’s architecture, checks its hash and signature and unpacks it next to the app. When Atelier quits (or on Restart), a helper script replaces the old app and clears the quarantine flag; on Restart it also starts the new one. Needs Atelier to be installed where it can replace itself, normally in Applications.
macOS, cannot replace itself If Atelier runs from a disk image, from a quarantined Downloads copy, or somewhere it cannot write, the sidebar and Settings offer Download instead: it saves the new disk image to your Downloads folder, checked against the feed’s hash, shows it in Finder, and you drag Atelier to Applications.
Windows Downloads in the background and runs the installer when you quit or restart. Windows builds are not code-signed, so the update signature below is what protects them.
Linux, AppImage Downloads in the background and replaces the AppImage file.
Linux, .deb Downloads in the background; installing asks for your password.
Other Linux packages and unpackaged builds Do not update: “This copy of Atelier can’t update itself. Install it from the releases page to get updates.” with a Releases page button.

Every package is signed by the publisher. Before downloading anything, the app fetches <package>.sig from the same feed and checks that it is an Ed25519 signature, by the key whose public half is built into the app, over this exact message: atelier-update:v1, the package’s file name, and the package’s SHA-512 as the update file states it. A package with no signature, or one made with another key, is refused:

  • “Atelier 0.1.10 is not signed, so it was not downloaded.”
  • “Atelier 0.1.10 is not signed with Atelier’s key, so it was not downloaded.”
  • “Couldn’t check the signature of Atelier 0.1.10.”
  • “Atelier 0.1.10 points outside its feed.” (an update file naming a file elsewhere)

After the download the app checks the package against the hash in the update file (“the file is damaged” otherwise), and on macOS that the unpacked app has this app’s bundle identifier. The feed’s address and your token are never sent anywhere but the feed itself. So a compromised update server, bucket or account cannot hand out an update of its own: it would need the publisher’s private key, which stays off the server. Differential downloads are off, so every update is a full download, about the size of the installer.

What this does not do: it does not make the downloads secret (the feed has to be readable by the app), and it does not help if the publisher’s private key is stolen. macOS builds are Developer ID signed and notarized, so the first install opens without a Gatekeeper warning; Windows builds are not signed, so SmartScreen warns on first install.

Settings › System › Check for updates automatically, on by default. Switched off, the app asks no feed anything by itself: not when it starts, not after you sign in, not every 5 minutes. It remembers the choice in updates.json. Check now still looks, changing the Update channel looks once, and an update that was already downloaded still installs. With it off and nothing ever checked, Updates says “Automatic checks are off. Check now looks for a new version.”

To remove the public feed as well, start the app with ATELIER_UPDATE_FEED=off (see Environment variables); a copy connected to a server still asks that server. What an update check sends is in What leaves your machine.

  • Without a connection the check fails and Updates shows the error (the first line of what went wrong). The next check, 5 minutes later or on Check now, tries again.
  • A failed download keeps an update that was already waiting. On Windows and Linux, electron-updater empties its download folder when a download fails, so the waiting update is dropped, the app says so, and the next check starts again.
  • “The server didn’t accept your sign-in. Sign in again to get updates.” means the server’s feed answered 401.
  • Nothing published yet on the public feed is not an error: the app reports that it is up to date.

The app does not show release notes. Changes are listed per version in CHANGELOG.md in the repository, and on the releases page next to the packages.

There is no rollback in the app. To go back, install the older version’s installer over the newer one (the releases page lists every version). Installing does not touch your data, but the database only moves forward: a newer version migrates it when it starts, and nothing stops an older version from opening it afterwards. Back up your data folder before updating and restore it when you roll back (Data and files). If the feed would offer the newer version again, switch the checks off first.

The server tells admins in Settings › Admin › Server: its version, the newest one, and what to do.

  • With the Compose file’s updater service, Update server pulls the new images and recreates the server and the sandbox. Everyone is disconnected for a minute or so and reconnects by themselves.
  • Without it: docker compose pull && docker compose up -d on the host, in the folder with compose.yaml. Your data volume is kept.
  • A server built from source is updated by rebuilding it.

Details, the updater’s security trade-off and pinning a version are in Run a server. After a server update:

  • Desktop apps that are older than the server show a notice in the sidebar: “The server runs Atelier 0.1.9, newer than this app. Some features may not work as intended.” An app newer than its server tells admins: “The server runs an older version (0.1.7). Update it in Settings › Admin › Server.”
  • A web page left open shows “The server was updated to Atelier 0.1.10.” with Reload.

The server only looks up the newest version when an admin opens the Server page or presses Check now; it never updates itself.

For people who build and distribute their own copy of Atelier. Atelier’s own releases follow the same steps.

Part Role
electron-builder Builds the installers and writes latest.yml (Windows), latest-mac.yml and latest-linux.yml.
The release workflow (.github/workflows/release.yml) On a v* tag, builds the macOS, Windows and Linux packages on GitHub’s runners and attaches them, with the update files, to the tag’s release. A tag with - is a prerelease.
The server image workflow (.github/workflows/server-image.yml) On the same tag, builds the server, sandbox and updater images for amd64 and arm64.
The public feed (deploy/cloudflare) A Cloudflare Worker over an R2 bucket that serves stable/ and beta/ with byte ranges (downloads resume) and a download page.
deploy/cloudflare/publish.mjs Signs each package and uploads packages first, update files last.
A server’s feed (ATELIER_UPDATES_REPO) Mirrors a GitHub release for the apps connected to that server.

Apps install only what is signed by the key whose public half is APP.updatePublicKey in packages/protocol/src/app.ts, and the address they ask is APP.updateFeed. A fork that ships its own builds makes its own key pair and builds with both changed; builds made with Atelier’s key can only be signed by whoever holds that key.

Terminal window
openssl genpkey -algorithm ed25519 -out ~/.atelier-release/update-signing.key
# the raw public key, base64: this is the value for APP.updatePublicKey
openssl pkey -in ~/.atelier-release/update-signing.key -pubout -outform DER | tail -c 32 | base64

Back the private key up. If it is lost, apps already installed cannot be updated: people have to install a build that carries a new public key.

Once, with a Cloudflare account (wrangler runs through npx):

Terminal window
cd deploy/cloudflare
npx wrangler login
npx wrangler r2 bucket create atelier-releases
npx wrangler deploy

Set the Worker’s custom domain in wrangler.toml (routes) and put the same address in APP.updateFeed. For each version, with the packages and their latest*.yml files collected in one folder (for example gh release download <tag>):

Terminal window
node deploy/cloudflare/publish.mjs installers stable # or: beta

Build all of an OS’s targets in one run: a Linux latest-linux.yml must list both the AppImage and the .deb or a copy installed from the other kind finds nothing to update to (the script warns). Publish the feed after the server image is pushed, or a server updated in between pulls the previous image. Apps pick the new version up at their next check, within 5 minutes. curl https://<feed>/stable/latest.yml shows what is published.

Set ATELIER_UPDATES_REPO and ATELIER_UPDATES_TOKEN on the server. The apps connected to it then update from the newest GitHub release of that repository. Apps require a signature for every package, so each package needs a <package>.sig file next to it as a release asset. The release workflow makes them when the repository has an UPDATE_SIGNING_KEY secret; otherwise run node deploy/cloudflare/sign-release.mjs <folder with the packages> with the key and upload the .sig files (gh release upload <tag> <folder>/*.sig). A signature is the base64 Ed25519 signature of the message described above; deploy/cloudflare/signing.mjs has the code (signPackage, sha512Of, loadKey). Without them, apps report “Atelier … is not signed, so it was not downloaded.” Details: Run a server.

The base build config signs nothing. A signed and notarized Mac build is made on a Mac that has a Developer ID Application certificate and a saved notarization login (xcrun notarytool store-credentials), with:

Terminal window
pnpm --filter @atelier/desktop package:mac # sign arm64 and x64, send both to Apple, stop
pnpm --filter @atelier/desktop package:mac --status # what does Apple say?
pnpm --filter @atelier/desktop package:mac --finish # when both are accepted: staple, check, make the .dmg and .zip and latest-mac.yml

Apple’s first notarizations for a new account can take hours, so the script never waits. Replace the CI’s unsigned macOS files on the release with the finished ones before publishing the feed. The update signature is a separate layer and still applies to every package. The full procedure, with every file involved, is docs/updates.md in the repository.