StartOS version 0.4.1.1 came out and required users to trust signing keys to install services. The guide below was aimed to assist for that specific version. Since then, 0.4.1.2 , was released - providing easier interactions with the signing keys - particularly, when you add a custom registry it gives you the option right then to trust those keys. If you are still on 0.4.1.1 - the guide below may help.
There are three ways to install a service from a custom registry. The preferred approach is option one, but all three work, and you can use whichever you prefer.
Option 1: Approve the developer (best, and you only do it once)
Step 1: Get the developer’s public key.**
The public key is a block of text that starts with -----BEGIN PUBLIC KEY----- or -----BEGIN PGP PUBLIC KEY BLOCK-----.
To find it:
- In the Marketplace, choose the registry and open the service you want.
- Under Source Code, click StartOS package. This opens the developer’s project page, usually on GitHub.
- Scroll down to the description below the file list. Press Ctrl+F (Cmd+F on a Mac) and search for
public keyorsigning key. - If it’s not there, check Releases on the right side of the page.
This requirement is new, so many developers haven’t published their key yet. If you can’t find it, ask for it:
-
On the same GitHub page, click Issues at the top, then New issue.
-
Title it Please publish your package signing key and paste something like this:
StartOS 0.4.1 only installs packages signed by a key the user trusts. Could you publish the public key your packages are signed with (here in the description, and somewhere else you control, like your website), so users can add it under System → Trusted keyrings?
Step 2: Add the key to your server.
- Go to System → Trusted keyrings and click Add.
- Under Name, type a label for this keyring, such as the developer’s name. It’s just there to help you recognize it later.
- Under Public keys, paste the key.
- Click Save.
Step 3: Install.
Open the Marketplace, choose the same registry from your list, and open the service. The Install button now works. Updates will too, from now on.
Option 2: Sideload it (no key needed, no command line)
Use this if the developer hasn’t published a key and you trust them.
- Download the service’s
.s9pkfile from the developer’s release page (often on GitHub). Choose the file ending in:_x86_64.s9pkfor most servers_aarch64.s9pkfor a Raspberry Pi
- On your server, click Sideload at the top of the screen.
- Drag the file in.
- StartOS warns you that nobody you’ve approved signed it. If you trust the developer, click Install anyway.
You’ll repeat these steps for each update.
Option 3: The command line (for people comfortable with a terminal)
-
Open Terminal (Mac or Linux) or PowerShell (Windows).
-
Connect to your server:
ssh start9@your-server-name.localThe first time, it asks whether you want to continue connecting. Type
yes. When it asks for a password, enter your StartOS master password (the one you use to log in to StartOS). Nothing appears on screen while you type. That’s normal. -
See what’s in the registry. Replace the address with your registry’s address (the one you added in the Marketplace):
start-cli -r https://registry.example.com registry package index --format json | jq -r '.packages | to_entries[] | "\(.key) = \([.value.versions[]][0].title)"'You’ll get a list like this. The short name is on the left:
bitcoind = Bitcoin Knots vikunja = Vikunja -
Install the service, using its short name from step 3:
sudo start-cli -r https://registry.example.com package install vikunja --trust
To update later, run step 4 again.
A word of caution about Options 2 and 3
Both options tell your server “I’m vouching for this myself.” StartOS still checks that the file wasn’t damaged or tampered with, but it no longer checks who made it. A bad package could do bad things, so only do this for developers you trust.