Collection Storage

Radicale v3

Example for a simple storage layout

• [d]: directory
• [f]: file

[d] /var
└─[d] /lib
  └─[d] /radicale
    └─[d] /collections
      └─[d] /collection-root
        ├─[d] /USER1
        │ ├─[d] /mycalendar1 (Collection)
        │ │ ├─[d] /.Radicale.cache (automatic generated)
        │ │ ├─[f] .Radicale.props (tag: VCALENDAR)
        │ │ ├─[f] schedule1.ics
        │ │ ├...
        │ │ └─[f] scheduleX.ics
        │ ├─[d] /myaddressbook1 (Collection)
        │   ├─[d] /.Radicale.cache (automatic generated)
        │   ├─[f] .Radicale.props (tag: VADDRESSBOOK)
        │   ├─[f] contact1.vcf
        │   ├...
        │   └─[f] contactX.vcf
        │
        ├─[d] /USER2
        ¦

Collection

Collection on storage is always a directory containing

Files: *.ics / *.vcf

Collection Type	Files
VCALENDAR	*.ics
VADDRESSBOOK	*.vcf

File: .Radicale.props

Property file of collection

Example using jq for pretty-print

Example of a calendar collection

jq . .Radicale.props 
{
  "C:calendar-description": "Schedules",
  "C:supported-calendar-component-set": "VEVENT,VJOURNAL,VTODO",
  "D:displayname": "Schedules",
  "ICAL:calendar-color": "#ffc000ff",
  "tag": "VCALENDAR"
}

Example of a addressbook collection

jq . .Radicale.props 
{
  "CR:addressbook-description": "AddressBook",
  "D:displayname": "AddressBook",
  "{http://inf-it.com/ns/ab/}addressbook-color": "#758857ff",
  "tag": "VADDRESSBOOK"
}

Directory: .Radicale.cache

[d] /var
└─[d] /lib
  └─[d] /radicale
    └─[d] /collections
      └─[d] /collection-root
        ├─[d] /USER1
        ¦ ├─[d] /mycalendar1 (Collection)
          ¦ ├─[d] /.Radicale.cache (automatic generated)
            ¦ ├─[d] /item (automatic generated)
              ├─[d] /history (automatic generated)
              └─[d] /sync-token (automatic generated)

Directory: .Radicale.cache/item

1:1 reflecting items in a pre-compiled format

Since 3.3.2 the item cache can be located outside by option [storage] use_cache_subfolder_for_item = True in combination with defined filesystem_cache_folder.

Since 3.3.2 the item cache format can be toggled between SHA-256 or using mtime+size of original item by option [storage] use_mtime_and_size_for_item_cache = True (recommend to use only on systems where mtime has "ns" granularity)

Directory: .Radicale.cache/history

historic pre-compiled items

Since 3.3.2 the history can be located outside by option [storage] use_cache_subfolder_for_history = True in combination with defined filesystem_cache_folder.

Directory: .Radicale.cache/sync-token

file containing synchronization tokens related to each client serve only changes on request

Since 3.3.2 the sync-token can be located outside by option [storage] use_cache_subfolder_for_synctoken = True in combination with defined filesystem_cache_folder.

Cache Folder

Since 3.3.2 there is the option to store the cache outside the filesystem_folder e.g. [storage] filesystem_cache_folder = /var/cache/radicale/collections/collection-cache

This can be used storing item cache local on the system while the items, sync-token and history are stored in shared filesystem like NFS or GlusterFS.

Item Storage	Item Cache	History	Sync-Token
Local	possible	possible	possible
Remote, single instance	optional(1)	optional(1)	optional(1)
Semi-Local or shared, cluster	possible(1)	avoid(2)	avoid(2)

⁽¹⁾ can decrease response time

⁽²⁾ will break consistency

Example:

[d] /var
└─[d] /lib
  └─[d] /radicale
    └─[d] /collections
      ├─[d] /collection-cache
      | ├─[d] /USER1 (1:1 related to below)
      | ¦ ├─[d] /mycalendar1 (1:1 related to below)
      |   ¦ ├─[d] /.Radicale.cache (automatic generated)
      |     ¦ └─[d] /item (automatic generated)
      |
      └─[d] /collection-root
        ├─[d] /USER1
        ¦ ├─[d] /mycalendar1 (Collection)
          ¦ ├─[d] /.Radicale.cache (automatic generated)
            ¦ ├─[d] /history (automatic generated)
              └─[d] /sync-token (automatic generated)

Activation of Cache Folder

Directory: .Radicale.cache/item

Content may be moved, otherwise it's automatic re-generated on next request by client (one-time response delay depending on amount of items)

Directory: .Radicale.cache/history

Content may be moved (in case of interest), otherwise historic data is lost

Directory: .Radicale.cache/sync-token

Content may be moved, otherwise lost and client will on next connection pull more data than usual if sync-token is used on client side

Database folder for collection sharing

Since 3.7.0 there is the option to share collection using internal database, either single csv or per share file based.

Example for "csv"

File location can be controlled by option [sharing] database_path = /var/lib/radicale/collections/collections-db/sharing.csv.

[d] /var
└─[d] /lib
  └─[d] /radicale
    └─[d] /collections
      ├─[d] /collection-db
      | └─[f] /sharing.csv
      ¦

Example for "files"

Base directory location can be controlled by option [sharing] database_path = /var/lib/radicale/collections/collections-db.

[d] /var
└─[d] /lib
  └─[d] /radicale
    └─[d] /collections
      ├─[d] /collection-db
      | ├─[d] /map
      | | ├[f] /ENCODED_SHARE-BY-MAP-1
      | | ├[f] /ENCODED_SHARE-BY-MAP-2
      | | ¦
      | | 
      | └─[d] /token
      |    ├[f] /TOKEN-1
      |    ├[f] /TOKEN-2
      ¦    ¦