citadel/docs/realms.md

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/user` in the realm, populated from `/realms/skel`
 * `/rootfs` : btrfs subvolume clone (snapshot) of an application image.
    

#### Realm instance directory layout

    /realm-main
        config
        /home
        /rootfs