π«π· Version franΓ§aise
Install with apt (Debian / Ubuntu)
See also: Three ways to run Orkeon Β· Verify what you install Β· Security policy Β· Publication matrix Β· Back to the index
Add the Orkeon source to apt once, then manage Orkeon like any other package:
apt install orkeon, apt update, apt upgrade. No .deb to download again at every
version.
The repository serves two packages:
| Package | Contents |
|---|---|
orkeon |
the orkeon CLI at /usr/bin/orkeon, the interactive console orkeon-repl at /usr/bin/orkeon-repl (the one that runs the *.cmd.ts scripted commands) β self-contained, it never pulls a dotnet-runtime package or a Microsoft repository |
orkeon-archive-keyring |
the public key apt checks the repository with, at /usr/share/keyrings/orkeon-archive-keyring.gpg β so a new signing key reaches you through apt upgrade |
It is built for Debian 12 and 13 and Ubuntu 22.04, 24.04 and 26.04, on amd64 and
arm64. Derivatives (Linux Mint, Pop!_OS, Ubuntu under WSL) follow their Ubuntu or Debian
base. Ubuntu 20.04 and older are not supported: the package needs libc6 (>= 2.34).
Nothing in Orkeon adds this source for you β neither the .deb nor the install.sh of the
archives: you run the commands below yourself.
Set it up
Copy the block below into a terminal. It works from a bare Debian or Ubuntu image, under a
user that can sudo:
sudo apt-get update && sudo apt-get install -y ca-certificates curl
curl -fsSL -o /tmp/orkeon-archive-keyring.gpg \
https://github.com/Orkeon/orkeon/raw/apt/orkeon-archive-keyring.gpg
echo "0cc5e804e1ee49c50ec5b23145ee7ee65d4834a08b8dc38914674249dfcc6a21 /tmp/orkeon-archive-keyring.gpg" | sha256sum --check
sudo install -m 0644 /tmp/orkeon-archive-keyring.gpg /usr/share/keyrings/orkeon-archive-keyring.gpg
sudo tee /etc/apt/sources.list.d/orkeon.sources > /dev/null <<'EOF'
Types: deb
URIs: https://github.com/Orkeon/orkeon/
Suites: raw/apt/stable/
Include: orkeon orkeon-archive-keyring
Signed-By: /usr/share/keyrings/orkeon-archive-keyring.gpg
EOF
sudo apt-get update && sudo apt-get install -y orkeon orkeon-archive-keyring
To install the dev build of
main, see Install a dev build. The block installs fromstable, which carries final versions only: while that channel holds nothing,apt-get updatestops on it with "does not have a Release file" (a channel never published) or the install with "Unable to locate package orkeon" (a channel still empty).
Then, as with every other channel:
orkeon init # writes ~/.config/Orkeon/appsettings.json
orkeon run crew.yaml
Why each line is there:
ca-certificatesandcurlare missing from the base images; apt needs the first to reach GitHub over HTTPS.- The key is checked before it is trusted. The first download of a key is trust on first
use:
sha256sum --checkcompares it with the SHA-256 published in the security policy onmain, and stops the block on any difference. - The key is a binary file in mode 0644. apt checks signatures as the unprivileged
_aptuser, and an ASCII-armoured file saved under a.gpgname fails withNO_PUBKEYon apt 2.4 to 2.8. - The source is a deb822
.sourcesfile with aSigned-By:line: the key is trusted for this source only, never system-wide. Noapt-key, nothing under/etc/apt/trusted.gpg.d.Include:restricts the source to the two Orkeon packages on apt 3.1 and later; older apt ignores the field. orkeon-archive-keyringis installed explicitly.orkeononly recommends it, and--no-install-recommendsβ common in Dockerfiles β would skip it. Once installed, the package owns the key file you placed by hand and keeps it current.
The same source file is kept in the repository as
installers/apt/orkeon.sources.
Everyday use
| You want to⦠| Command |
|---|---|
| Install | sudo apt install orkeon orkeon-archive-keyring |
| Update | sudo apt update && sudo apt upgrade |
| See the versions the channel offers | apt list -a orkeon (or apt-cache policy orkeon) |
| Go back to an earlier version | sudo apt install orkeon=<version> |
| Stay on a version | sudo apt-mark hold orkeon (unhold to follow the channel again) |
| Check what runs | orkeon --version |
Version strings. apt writes the pre-release separator as ~, which sorts a pre-release
before its final version: a release tagged v<X.Y.Z>-<pre> is the package version
<X.Y.Z>~<pre>, so going back to it is sudo apt install orkeon=<X.Y.Z>~<pre>. apt asks you to
confirm a downgrade; in a script, sudo apt-get install -y --allow-downgrades orkeon=<version>.
Every version still attached to a GitHub Release stays in its channel, so going back always
has somewhere to go. A version withdrawn for a defect disappears from the channel at the next
apt update (see Withdrawn versions).
Your settings are not part of the package: ~/.config/Orkeon/appsettings.json, written by
orkeon init, survives updates, downgrades and removal.
Channels
| Channel | Suites: line |
Carries |
|---|---|---|
stable |
raw/apt/stable/ |
final versions only (a tag without a pre-release segment, such as vX.Y.Z) |
rc |
raw/apt/rc/ |
every tagged release β the release candidates and the final versions |
dev |
raw/apt/dev/ |
builds of main between two releases β see Follow main |
stable carries the final releases: it is the channel to follow. The rc channel adds the
release candidates of the next version β every final version reaches rc too, so a machine
on rc never misses one β and dev carries the pre-release builds of main.
Switch channel by editing the Suites: line, then update:
sudo sed -i 's|^Suites: .*|Suites: raw/apt/rc/|' /etc/apt/sources.list.d/orkeon.sources
sudo apt update && sudo apt upgrade
Moving to a channel with newer versions is an ordinary upgrade. Moving back to a channel whose
newest version is older than the one installed (from dev to rc, from rc to stable)
upgrades nothing: apt keeps the installed version until the channel offers a newer one. To
go back at once, install a version of the new channel explicitly:
sudo apt install orkeon=<version>.
Edit only the channel name on that line: the rest of the path must match what the repository's index declares, or apt warns "Conflicting distribution" at every update.
Follow main (dev builds)
The dev channel carries the orkeon package built from every commit of main that CI
validated, between two releases:
Suites: raw/apt/dev/
- A build appears a few minutes after CI passes on a push to
main. Its packages are attached to theapt-devprerelease of the repository β one fixed tag that never moves, and not a release. - Versions look like
<X.Y.Z>~<pre>.dev.<n>,nbeing the number of the CI run that validated the commit, so it grows at every build: above the release they start from, below the next one β so a dev machine moves to the next release candidate by a plainapt upgradewhen it is published. After a final version, the dev builds move to the next patch (1.0.1~dev.<n>after1.0.0), as the NuGet dev channel does. - Only the three latest builds are kept. An older one leaves the channel;
apt install orkeon=<version>can only go back that far. - Unstable and unsupported. A dev build is not a release: it can break between two
updates, and bugs found on one are fixed on
main, never on the build. Pin a released version (rcorstable) for anything that must keep working. - apt only. Dev builds are never published to NuGet.org; the
orkeondotnet tool followsmainthrough its own channel on GitHub Packages, described in Three ways to run Orkeon.
Install a dev build
On a machine without the source, run the setup block with one change:
before you paste it, replace Suites: raw/apt/stable/ by Suites: raw/apt/dev/. Everything
else β the key, its SHA-256 check, the source file β stays as it is.
On a machine that already has the source (on stable or rc), switch it to dev:
sudo sed -i 's|^Suites: .*|Suites: raw/apt/dev/|' /etc/apt/sources.list.d/orkeon.sources
sudo apt-get update && sudo apt-get install -y orkeon orkeon-archive-keyring
orkeon --version # <X.Y.Z>-<pre>.dev.<n>
Then, to take the newest dev build: sudo apt update && sudo apt upgrade.
The source file, the key and the commands are those of the other channels β the dev channel
carries orkeon-archive-keyring too; only the Suites: line differs.
Remove
In this order β the source first, then the packages:
sudo rm /etc/apt/sources.list.d/orkeon.sources
sudo apt purge orkeon orkeon-archive-keyring
sudo apt update
Purging the keyring while the source is still declared makes every later apt update fail on
a missing key. Your ~/.config/Orkeon stays where it is; delete it yourself if you want it
gone.
What apt checks, and what you check once
apt checks, at every update and install, without you:
- the signature of the channel's index (
InRelease), against the key in/usr/share/keyrings/orkeon-archive-keyring.gpgand that key only; - the SHA-256 of every package it downloads, against the index β a package that differs by a single byte is refused ("Hash Sum mismatch").
You check once, when you add the source:
- the SHA-256 of the key file β the
sha256sum --checkline of the block does it; - optionally, the key's fingerprint, published in the security policy:
orkeon-archive-keyring fingerprint: 4765 9C57 4882 5078 5C78 2C37 1CF8 CD8A 4C20 1A2E
orkeon-archive-keyring.gpg sha256: 0cc5e804e1ee49c50ec5b23145ee7ee65d4834a08b8dc38914674249dfcc6a21
The same two lines are published in the security policy; the CI guard checks both pages, and the SHA-256 of the block above, against the certificate.
gpg --show-keys /usr/share/keyrings/orkeon-archive-keyring.gpg # needs the gnupg package
The primary key line must show that fingerprint and the user id
Orkeon Archive Signing Key <arion@orkeon.org>.
The packages themselves are the assets of the GitHub Releases, so each one also carries the
build provenance attestation and the SHA256SUMS line described in
Verify what you install.
Docker images
A Dockerfile installs from the repository like a machine does, with two cautions:
- Rate limits. The index is served by
raw.githubusercontent.com, which limits anonymous traffic and may answer429.apt updateturns that into a warning and keeps the index it had β but a fresh image has none, so the nextapt-get installfails. Retry, and keep the key out of the build's downloads. --no-install-recommendsskipsorkeon-archive-keyringunless you name it β keep it in the list.
Verify the key once on your machine with the block above, put orkeon-archive-keyring.gpg and
orkeon.sources
next to the Dockerfile, then:
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates
COPY orkeon-archive-keyring.gpg /usr/share/keyrings/orkeon-archive-keyring.gpg
COPY orkeon.sources /etc/apt/sources.list.d/orkeon.sources
RUN chmod 0644 /usr/share/keyrings/orkeon-archive-keyring.gpg /etc/apt/sources.list.d/orkeon.sources \
&& apt-get -o Acquire::Retries=5 update \
&& apt-get install -y --no-install-recommends orkeon orkeon-archive-keyring \
&& rm -rf /var/lib/apt/lists/*
ca-certificates comes first: without it, apt cannot reach the Orkeon source over HTTPS.
Withdrawn versions
A version found defective after its release can be withdrawn from a channel: the index is
signed again without it, and your next apt update no longer offers it. An installed copy
stays installed β apt upgrade moves it to the newest remaining version, or
sudo apt install orkeon=<version> to a chosen one. A published package is never replaced
by other bytes under the same version: a fix always comes as a new version.
Troubleshooting
| Message | Cause | Fix |
|---|---|---|
NO_PUBKEY |
The key file is missing, or is an ASCII-armoured file saved as .gpg |
Run the block again: it installs the binary key in mode 0644 |
EXPKEYSIG |
The key on the machine is outdated β the repository is signed with a newer one | sudo apt install orkeon-archive-keyring if apt still lets you, otherwise download and check the key again with the block's lines up to sudo install |
Conflicting distribution |
The Suites: line was edited beyond the channel name |
Restore the line from the channel table, trailing / included |
429 Too Many Requests |
GitHub's limit on anonymous traffic | Retry later; in a Docker build, retry the step (-o Acquire::Retries=5) |
Hash Sum mismatch right after a release |
GitHub's cache still served the previous index for a few minutes | Wait a few minutes, then sudo apt update again |
| Signature errors after a key revocation was announced | The signing key was revoked | Follow the instructions published in the security policy: this is the only case where you must download a new key yourself |
Without the repository
A machine that cannot reach GitHub's raw content can still install a single version: download
orkeon_<version>_amd64.deb (or _arm64.deb) and SHA256SUMS from the
Releases, where <version> is the tag's version
(without the v), then:
grep " orkeon_<version>_amd64.deb$" SHA256SUMS | sha256sum --check # expect: OK
sudo apt install ./orkeon_<version>_amd64.deb
Such an install receives no updates: apt only upgrades from a source it knows.