# HG changeset patch # User Paul Boddie # Date 1457719692 -3600 # Node ID 3ec032d69fc3cec20412c84b28ca65b3b18933c4 # Parent 3af9af02d14a8a19355c9dba5950e5a9999d944d Updated the documentation to cover configuration settings and schema details. diff -r 3af9af02d14a -r 3ec032d69fc3 docs/wiki/Configuration --- a/docs/wiki/Configuration Fri Mar 11 18:34:56 2016 +0100 +++ b/docs/wiki/Configuration Fri Mar 11 19:08:12 2016 +0100 @@ -16,10 +16,15 @@ == System-Level and Tool Configuration == -Given a choice of [[../SystemUsers|system users and groups]], the -resulting configuration must be indicated in the `config.sh` file. Since -the `tools/install.sh` script depends on this configuration, changes must -be made to the file in the `tools/config.sh` location before installation +The `config.sh` file must indicate choices in the following areas: + + * The [[../DataStore|data store]] type to be employed + + * The [[../SystemUsers|system users and groups]] involved with running the + software and storing data + +Since the `tools/install.sh` script depends on this configuration, changes +must be made to the file in the `tools/config.sh` location before installation can occur. == Software Configuration == diff -r 3af9af02d14a -r 3ec032d69fc3 docs/wiki/DataStore --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/DataStore Fri Mar 11 19:08:12 2016 +0100 @@ -0,0 +1,17 @@ += Data Store = + +The data store for imip-agent holds calendar data and free/busy information. +The following data store types exist: + + * A [[../FileStore|file store]] employing textual files in the filesystem + + * A [[../DatabaseStore|database store]] employing database tables managed + by a database management system + +For simplicity, the file store is the default storage mechanism for imip-agent, +but the database store is provided as an alternative where different operating +characteristics are desired. + +The [[../Configuration|configuration]] files (`config.sh` and `config.py`) need +updating to reflect the choice of data store, with the directory parameters +set to appropriate values for the chosen store type. diff -r 3af9af02d14a -r 3ec032d69fc3 docs/wiki/DatabaseStore --- a/docs/wiki/DatabaseStore Fri Mar 11 18:34:56 2016 +0100 +++ b/docs/wiki/DatabaseStore Fri Mar 11 19:08:12 2016 +0100 @@ -13,3 +13,110 @@ The [[../FileStore|file store]] offers a more convenient method of managing calendar data, albeit offering arguably less scalability and less convenience when data volumes become significantly large. + +== Configuration Settings == + +The [[../Configuration|configuration]] files (`config.sh` and `config.py`) need to be +updated when choosing a database store. + +{{{#!table +'''File''' || '''Setting''' || '''Value''' || '''Description''' +== +`config.sh` +|| `STORE_TYPE` +|| `postgresql` +|| Selects a specific database store type; currently, only `postgresql` + .. is supported +== +`config.py` +== + `config.py` +|| `STORE_DIR` +|| `dbname=imip_agent` +|| Indicates a connection string for the store database +== +`JOURNAL_DIR` +|| `dbname=imip_agent` +|| Indicates a connection string for the journal database +}}} + +== Journal Structure == + +The journal information is retained in a collection of tables. Unlike the structure of +the [[../FileStore|file store]] in the [[../FilesystemUsage|filesystem]], each table +contains details for all quota groups, with each query indicating the group to select +the appropriate information. + +{{{#!table +'''Table''' || '''Purpose''' +== +`quota_freebusy` +|| Period descriptions describing reservations for resources sharing a quota (`quota`) +.. made by users or groups (`user_group`), structured similarly to the `freebusy` table +.. in the data store +== +`quota_limits` +|| A mapping from user identities or group identifiers to quota limits +== +`user_freebusy` +|| Period descriptions for reservations made in the context of a quota (`quota`) by a +.. specific user (`store_user`), structured similarly to the `freebusy` table in the +.. data store +== +`user_groups` +|| A mapping from user identities to group identifiers indicating the sharing of a quota +.. across a number of users +}}} + +== Store Structure == + +The store information is retained in a collection of tables. Unlike the structure of +the [[../FileStore|file store]] in the [[../FilesystemUsage|filesystem]], each table +contains details for all users, with each query indicating the user to select +the appropriate information. + +{{{#!table +'''Table''' || '''Purpose''' +== +`countered_objects` +|| Retains counter-proposals corresponding to events held in the `objects` table +.. received by each user (`store_user`) from another user (`other`) +== +`countered_recurrences` +|| Retains counter-proposals corresponding to events held in the `recurrences` table +.. received by each user (`store_user`) from another user (`other`) +== +`freebusy` +|| Period descriptions indicating start and end datetimes (in UTC), unique identifier +.. (`object_uid`), transparency, recurrence identifier (`object_recurrenceid`), +.. summary and organiser, reflecting the schedule of each user (`store_user`) +== +`freebusy_offers` +|| Period descriptions for scheduling offers made by counter-proposals sent by each +.. user (`store_user`) +== +`freebusy_other` +|| Period descriptions received or deduced for a user (`store_user`) structured +.. similarly to the user's own `freebusy` records +== +`freebusy_providers` +|| Details of [[../EventRecurrences|recurring events]] for which new free/busy records +.. must be [[../CronIntegration|periodically generated]] because these events recur +.. indefinitely, selectable for each user (`store_user`) +== +`freebusy_provider_datetimes` +|| Date/time details associated with the `freebusy_providers` information +== +`objects` +|| Records for each user (`store_data`) containing received event data (`object_text`) +== +`requests` +|| A collections of records, each belonging to a specific user (`store_user`) +.. consisting of a unique identifier (`object_uid`), normalised recurrence identifier +.. (`object_recurrenceid`) if appropriate, and (optionally) a scheduling method, +.. indicating the availability of an incoming scheduling request for handling by a user +== +`recurrences` +|| Records for each user (`store_data`) containing received recurrence event data +.. (`object_text`) +}}} diff -r 3af9af02d14a -r 3ec032d69fc3 docs/wiki/FileStore --- a/docs/wiki/FileStore Fri Mar 11 18:34:56 2016 +0100 +++ b/docs/wiki/FileStore Fri Mar 11 19:08:12 2016 +0100 @@ -13,3 +13,28 @@ Thus, the [[../DatabaseStore|database store]] exists as an alternative, offering different characteristics to those of the file store. + +== Configuration Settings == + +The [[../Configuration|configuration]] files (`config.sh` and `config.py`) need to be +updated when choosing a file store. + +{{{#!table +'''File''' || '''Setting''' || '''Value''' || '''Description''' +== +`config.sh` +|| `STORE_TYPE` +|| `file` +|| Selects the default file storage type +== +`config.py` +== + `config.py` +|| `STORE_DIR` +|| `/var/lib/imip-agent/store` +|| Indicates the filesystem location of the data store +== +`JOURNAL_DIR` +|| `/var/lib/imip-agent/journal` +|| Indicates the filesystem location of the journal +}}} diff -r 3af9af02d14a -r 3ec032d69fc3 docs/wiki/FrontPage --- a/docs/wiki/FrontPage Fri Mar 11 18:34:56 2016 +0100 +++ b/docs/wiki/FrontPage Fri Mar 11 19:08:12 2016 +0100 @@ -165,6 +165,7 @@ * [[/CalendaringSupport|Calendaring Support]] * [[/CounterProposals|Counter-Proposals and Offers]] * [[/CronIntegration|Cron Task Scheduler Integration]] + * [[/DataStore|Data Store]] * [[/EventRecurrences|Event Recurrences]] * [[/FilesystemUsage|Filesystem Usage]] * [[/IncomingMessages|Incoming Messages]]