= Citadel Realms
  [topic]
@link[guide >index#user]

Citadel contains only the base operating system and the GNOME desktop, it does not
include any applications. To be able to install and run applications Citadel can
create spaces which are called Realms.

A Realm is a container similar to a Docker or LXC container in which any Linux
distribution could be installed.  We use a Debian based image but it would not be
difficult to create an image for another Linux distribution.

The realm containers are launched with systemd-nspawn but this is a detail of
how they are implemented and not something it is necessary to learn about in 
order to use them.

== The $em(current) realm

Multiple realms may be launched at once but the GNOME Desktop is only associated with
one of the running realms.  This realm is called the `current` realm.

When displaying applications available to launch from the desktop, GNOME will only
be aware of applications that are installed in the realm which is set as `current`
and any application launched from the desktop will run inside this current realm.

Setting another realm as current does not affect any applications that are already running.
Changing the current realm only means that any further applications which are launched
will now run in the newly chosen realm.

== Realm 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.

[screen]
    /realms
        config
        /Shared
        /skel
        /default.realm -> realm-main
        /realm-main
        /realm-project
        /realm-testing

=== /realms/config

This is the global realm configuration file. Options set in this file apply to every realm
unless the same option has been overridden with a different value in the config file for
a realm.

=== /realms/Shared

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.