3.8 KiB
Citadel Realms
In Citadel applications are installed into and run from spaces called Realms. Realms
are implemented internally as systemd-nspawn containers but you don't need to know
this because the realms command-line tool manages creating and launching containers
for you.
Application Images
The root filesystem for realms are called Application Images, but we usually just call them appimgs. We have created a framework for constructing these images from Debian based distributions which we use to build the default appimg that we provide, but we also encourage users to experiment with building their own images.
Tree Application Images
Tree images are the only type of application image which is currently implemented for realms.
The rootfs is a tree of files on the filesystem, and also it is a btrfs subvolume.
Block Application Images
default realm
One realm is always selected to be the default realm. The default realm
starts automatically when the system boots. The realms utility can be used
to change which realm is the default realm. Switching the default realm changes
the symlink /realm/default.realm to point to a different realm instance directory.
citadel:~# realms default
Default Realm: main
citadel:~# realms default project
[+] default realm changed from 'main' to 'project'
citadel:~# realms default
Default Realm: project
current realm
If any realms are running, then one realm is always the current realm. The current
realm is a realm that is being monitored by the citadel-desktopd daemon. This
daemon is responsible for safely copying application .desktop files from the running
realm instance to a temporary directory where they will be read by the GNOME desktop to
to display a menu of applications that can be launched.
Changing the current realm, changes the set of applications which are visible to
gnome-shell to only the applications installed in this realm. Also, any applications
started by gnome-shell will run in the current realm.
citadel:~# realms
Current Realm: main
Realms base directory layout
The realms base directory is stored on the storage partition at /storage/realms and is bind mounted to /realms on the root filesystem for convenience.
/realms
config
/Shared
/skel
/default.realm -> realm-main
/realm-main
/realm-project
/realm-testing
/realms/config file
This file is a template of the configuration file for individual realms. When a new realm is created this file in copied into the new realm instance directory. By modifying this file, the default configuration for new realm instances can be changed.
/realms/Shared directory
This directory is bind mounted to /home/user/Shared of each running realm that has the option use-shared-dir enabled. It's a convenient way to move files between different realms and between citadel and realms.
/realms/skel directory
Files which are added to this directory will be copied into the home directory of any newly created realm. The directory is copied as a tree of files and may contain subdirectories.
/realms/default.realm
A symlink which points to a realm instance directory of the default realm. The default realm is the realm which starts when the system is booted.
/realms/realm-$name
This is a realm instance directory, for a realm with $name as the realm name.
/realm-main
config
/home
/rootfs
config: configuration file copied from/realms/config/home: directory mounted to/home/userin the realm, populated from/realms/skel/rootfs: btrfs subvolume clone (snapshot) of an application image.
Realm instance directory layout
/realm-main
config
/home
/rootfs