keelOS

HomeWhy keelOSHow it worksAbout keelOSFAQFeature comparison

Features

kcell: Docker apps, each in a tiny VMNested virtualizationkeelRM: a BMC for machines without onePassthrough that survives a host restartSR-IOV: network cards and graphicsWindows 11 without workaroundsZFS underneathWeb, command line and APIRDP straight to the consoleMemory that is not wastedOld systems welcome

Market

MarketkeelNASkeelAuth

Performance

keelOS next to KVMCPUMemoryStorageNetworkGPU passthrough next to bare metal

Get started

QuickstartDownloadGuestsHardwareSource code and licences

Read

DocsArticles
中文日本語

Docs · 1.0

kcell Applications

This chapter covers the kcell menu: running Docker applications on keelOS. What you want to install is an application such as Jellyfin or Nextcloud, not a virtual machine, so day to day you just "pick an application, fill in a few fields, click create", and keel builds the kcell for you.

1. kcells and applications

  • A kcell is a small VM on keelOS that exists to run Docker. Volumes (the application's data) are datasets on the host's storage pool, and the ports containers publish are on the kcell's own LAN address.
  • An application is a compose project (one or several containers) inside a kcell. You can create one from a template (a single form, no YAML to write) or write your own compose file.
  • When you create an application, it can go into an existing kcell, or keel can create a dedicated kcell for it. The first time, when nothing exists yet, just create the application; you do not need to make a kcell first.

Note: kcell needs a storage pool (see Storage). Downloading templates and pulling images also needs the kcell to reach the internet, see §9.

Open kcell in the left menu. At the top of the page is a summary card (titled kcell, with the buttons New application… and New kcell… on the right), and below it one card per kcell.

The first row of each kcell card shows the name, the state (running, stopped, stopped (checkpoint), failed) and the LAN address, with Settings, On (Stop and Restart when running) and Delete on the right. The card has two tabs: Applications and Images.

2. Creating an application

  1. Click New application… at the top of the page (or New application in this kcell… on a kcell's card).
  2. In the New application dialog choose a template, or Custom compose… (write the compose file yourself, see §8).
  3. Fill in the form. The first field is the application name; the rest depend on the template: where the data goes (Mounts), environment variables, whether to open it through the front door, whether to log in with keelAuth. What to fill in for each template is explained on the template itself.
  4. Choose which kcell the application goes into: an existing one, or New kcell (named after the application). If you choose a new one, keel uses defaults for the rest (network, address, CPU, memory, Docker disk, volumes); click Advanced to change them.
  5. Click Create (Save and start when adding to an existing kcell). keel creates the kcell, starts it, pulls the images and starts the application; progress shows in the Deploy dialog.

The built-in templates are: Jellyfin, Emby, Plex, Navidrome, Audiobookshelf (media and music), Nextcloud, Paperless-ngx, Immich, Vaultwarden, Syncthing (files, documents, photos, passwords), Home Assistant, Uptime Kuma, Frigate, AdGuard Home, Pi-hole, qBittorrent, Open WebUI, Samba, the front door, and the photo inbox (photo-inbox). Newer and additional templates are installed from the market, see §10.

In the template list, a template that is not on this host but is in the market is greyed out with Install in the corner: click it to download just that one template (a few KB), and then it is ready to use. With no network, or if the market catalogue cannot be read, only the templates already on this host are listed.

Note: For applications that are reached from outside (Vaultwarden, Nextcloud, Paperless-ngx, Immich, the front door), keel gives each application a kcell of its own (the page says "... is offered to the outside: keel makes a separate kcell for it") and does not put it together with other applications, so one application's trouble does not drag another down. If an existing kcell already holds other applications, such an application is refused there; choose New kcell.

3. Where the data goes: mounts

Mounts in the application form lists the directories the application needs, each with a role: config, cache, data (the user's own data, such as a media or document library). For each mount you can choose:

  • None (not mounted) (for optional directories);
  • This kcell's volumes: keel creates a volume automatically (shown as "volume xxx (made automatically)"), or choose New volume… and give it a name;
  • Other host datasets: an existing dataset on the host's storage pool, mounted into the kcell as a volume. keel neither creates nor deletes it. Click Browse the files to look at the files in it;
  • keelNAS shares: mount a share on a keelNAS. keel has no account on the keelNAS, so you enter a keelNAS user who can read the share, and a Password; the password is stored in this application's compose file. For keelNAS see NAS.

Data mounts can be set to Read only (for example Jellyfin only needs to read the media library).

A new volume is added to a running kcell immediately, containers already running are left alone, and no restart is needed. An old kcell that was started before the upgrade needs one cold restart the first time you add a volume (the page says so), and not afterwards.

If an application has the same name as one you deleted earlier, the old volumes are still there and the new application picks up the old data in them; the form tells you so. To start from scratch, tick Delete its volumes too when you delete the application, see §7.

4. Memory check

A template declares roughly how much memory its application needs. When you add an application to a kcell, keel adds up the needs of the applications already in it:

  • If there is enough memory, the form shows "the application needs ... / the kcell has ...".
  • If there is not enough, it says "first raise the kcell's memory in its settings to at least ..., then add the application" and does not let you add it. Increase the memory under Settings and come back, or choose New kcell.
  • When a new kcell is created, keel sizes it by the memory the application needs.

Do not squeeze memory below what the application needs: containers get killed when memory runs out.

5. iGPU transcoding and opening through the front door

iGPU transcoding: the forms of Jellyfin and similar applications have an iGPU transcoding option (only when the host's integrated GPU can be split into VFs). Tick it and the kcell gets one VF of the host's integrated GPU, and containers see /dev/dri. Note:

  • For a kcell with an iGPU VF, Stop means a power-off with no checkpoint; containers exit and come back at the next start according to their restart policy.
  • Adding or removing the iGPU VF takes a cold restart of the kcell to take effect; when you save, keel restarts it and then starts the application.
  • In Jellyfin you must turn on transcoding yourself: Dashboard, Playback, Transcoding, choose VA-API as the hardware acceleration, device /dev/dri/renderD128, and tick hardware encoding.

Opening through the front door (https): web applications that are reached from outside can be served over https through the "front door". The front door is itself a template application (Front door, based on Caddy), and a host can have only one.

  1. First install the Front door application in some kcell. You may enter a domain name and an email (with both, Let's Encrypt is used); without them the front door uses its own CA, and you install http://<front door address>/ca.crt once in your browser.
  2. After that, when you create Vaultwarden, Nextcloud, Paperless-ngx or Immich, Open through the front door (https) is ticked by default in the form, and the application gets an https address.
  3. Once ticked, the application accepts connections only from the front door; visiting its LAN address directly is blocked by the firewall.

If there is no front door yet, the form says "This host has no front door yet: install the front door application in a kcell first...".

Log in with keelAuth: some templates have a Log in with keelAuth option (the host needs a keelAuth, see Accounts, Tokens and Permissions). Tick it and keel creates a login client and two groups in keelAuth (the application name, and "application name-admins") and writes the address, secret and CA into the application's configuration. Choose Who may use it (keelAuth groups); everyone in the chosen groups can use it; an administrator then adds people to "...-admins" to make them the application's administrators. If no keelAuth is available, this item says "This host has no keelAuth available".

Note: Vaultwarden's web client works only over https, so log in with keelAuth must be used together with Open through the front door.

6. The application list, snapshots and going back to before an update

The Applications tab of a kcell card is the application list. Each row has the application name (click to see its containers and mounts), the number of containers, the ports, and these buttons:

  • Change: opens the form for an application made from a template; opens the YAML editor for an application whose compose file was edited by hand;
  • Start, Stop, Pull: they correspond to docker compose up, down and pull, and the output is shown in a dialog;
  • Snapshots, Delete.

Ports are links; click one to open http://<the kcell's LAN address>:<port>/. By default ports are published only on the kcell's own LAN address, not on the host's address. To have them on the host's address too, tick Publish on the host's address too when you create the kcell or in its settings.

Snapshots

Click an application's Snapshots to see its snapshot list: the time, the reason (before an update, before a new kcell system, daily, by hand) and the datasets involved.

  • keel takes one automatically before an application is updated: at the next start after the compose file was changed or a new image was pulled; and before the kcell gets a new system (after a keelOS upgrade) it takes one for each application. A snapshot covers the application's own configuration-type volumes and its compose file. It does not cover data-type libraries (media libraries and the like) or datasets on the host: that is your data, and a rollback should not throw away what was added after the update.
  • Another one is taken every day (by UTC date); the keel setting kcell_daily_snap=false turns that off. Each application keeps the latest 5 before-update snapshots and 7 daily snapshots.
  • These snapshots carry a held mark: they cannot be removed even with zfs destroy on the host, and root inside the kcell cannot touch them at all.
  • Take one now takes one by hand.

Going back to before an update

If an application update breaks it, click Back to before the update on the snapshot row you want to return to, and confirm. keel first stops the application, rolls its volumes and compose file back to that snapshot, and starts it again. Data written to those volumes after the snapshot is lost, and snapshots newer than it are deleted; progress shows in the output box.

7. Deleting applications and kcells

Delete an application: stop the application first (0 containers), then click Delete. Delete its volumes too is unticked by default in the dialog: the volumes stay, and when you later create an application with the same name it picks up the old data in them. Tick it to delete the data as well; it cannot be recovered.

Delete a kcell: click Delete on the card. A running kcell needs Stop and delete (a normal shutdown first). Delete the volumes too is unticked by default: the volumes and the application directories are kept, moved to a holding place, and when you later create an application you can pick them again under "Other host datasets". Tick it to delete everything.

8. Writing your own compose

Choose Custom compose…, write the compose file (YAML) in the editor, give it an Application name, and click Save or Save and start. Relative paths (./data) end up under stacks/<application name>/ on the host; a kcell volume appears in the container as /vols/<volume name>.

You can also use docker from your own computer: add your SSH public key under the kcell's Settings (advanced) and cold-restart the kcell, and Docker from your computer on the card gives a command you can copy (a docker context). There are no ports 2375/2376 on the LAN, only SSH (keys only).

The Images tab lists the images in this kcell (Pull…, Clean up unused images). Images are the base files a container runtime uses, not installers: an image that a container uses cannot be deleted; old versions left behind after an application upgrade have no container using them and can be cleaned up.

9. Network and firewall

  • When you create a kcell and the host has several networks, you can choose the Network (LAN NIC). A network without an uplink port cannot get an address or pull images, and the list says so. The address is DHCP by default; you can also choose Fixed and enter Address/prefix length (such as 192.168.1.20/24) and Gateway.
  • Templates come with a firewall for the kcell's NIC: inbound allows only the ports the template declares (for example Vaultwarden allows only tcp/80, or only the front door's address when opened through the front door), outbound by default allows only the internet and DNS, and the LAN is not reachable. Applications that log in with keelAuth are also allowed to reach keelAuth. You do not configure any of this.
  • Media applications that must be discoverable on the LAN, such as Jellyfin and Plex, and applications that talk to LAN devices, such as Home Assistant and Uptime Kuma, have no restrictions in their templates.
  • A kcell made from your own compose file has none of these rules.

10. Updating templates

keelOS ships the basic templates above. New and updated templates are installed one by one under Application templates in the Market, or by clicking Install on a greyed-out template in the new application's template list. An installed template package replaces the built-in template of the same name only if it is newer than the current keelOS; delete the package and the built-in one is back. Applications already created are not affected.

11. kcell settings

Click Settings on a kcell card to open Settings of {name} (advanced):

  • Docker disk: can only grow (Grow to). It shows how much Docker has used so far;
  • SSH public keys: see §8;
  • CPU, memory, LAN address, note, Publish on the host's address too and so on. Next to each item it says Now or after a cold restart. For items that need a cold restart, keel asks after saving whether to restart now; on restart the containers exit and come back according to their restart policy.

If you set memory below what the applications need, the page warns that it is less than the applications need and that containers will be killed when memory runs out.

On / Stop: Stop saves the kcell's memory into a checkpoint, containers do not exit, and the next On continues where it left off. A kcell with an iGPU VF is the exception, see §5. Restart makes containers exit and come back according to their restart policy.

12. Limits in 1.0

  • A host can have only one front door.
  • Accounts inside a kcell's Docker applications are managed by the applications themselves, not by keel (except for applications that log in with keelAuth, where keel creates the groups and the client).
  • After a live move of a storage pool, the snapshots at the new location do not carry the held mark.
← Previous: Configuration: problems and advancedNext: Market →