1. Akonadi configuration
------------------------

Akonadi stores its settings and data in the subdirectory "akonadi" of the file
system locations specified by XDG Base Directory Specification [1a].

* Configuration files (e.g. akonadiserverrc) are stored in
  $XDG_CONFIG_HOME/akonadi/ (defaults to ~/.config/akonadi/). If the file
  cannot be found there, Akonadi will look in $XDG_CONFIG_DIRS/akonadi/
  (defaults to /etc/xdg/akonadi/).

* Similarly, data files are stored in $XDG_DATA_HOME/akonadi/
  (~/.local/share/akonadi/ by default). If the needed resource cannot be found
  there, Akonadi will look in $XDG_DATA_DIRS/akonadi/ (that is
  /usr/local/share/akonadi/ and /usr/share/akonadi/ by default) as well.

Please note that Akonadi never modifies config and/or data files in global
directories. Changed files are always written to $XDG_CONFIG_HOME/akonadi/ and
$XDG_DATA_HOME/akonadi/ respectively which will always have preference over
global files the next time Akonadi starts up.

[1a] http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

2. Akonadi storage backends
---------------------------

While Akonadi provides data caching, indexing and searching services for PIM
applications, it does not do most of raw data manipulation itself. It relays
these tasks to the external SQL database engine. Flexible Akonadi architecture
allows a user to choose from a range of well-known SQL database servers and use
them with Akonadi.

SQL server specific details are implemented in Akonadi storage backends which
are provided by the respective akonadi-backend-* packages. Just install the
backend package which is the most appropriate for your setup and edit
akonadiserverrc configuration file accordingly. By default Akonadi uses MySQL
backend which is configured to start a local instance of MySQL server for each
user using Akonadi.

At the moment, the following backends are supported:

* MySQL backend (default) provided by the akonadi-backend-mysql package.
  By default, the backend starts MySQL Server instance with privilegies of the
  user that started akonadiserver. Alternatively (with StartServer=false) the
  backend may connect to the specified database on the external MySQL server.

  This backend uses official QSql MySQL driver. The following configuration
  options are available:

  [%General]
  Driver=QMYSQL

  [QMYSQL]
  StartServer=   ; whether to start internal server instance, defaults to true
  Name=          ; database name
  Host=          ; name of host running external MySQL server
  User=          ; database user, external server only
  Password=      ; database user password, external server only
  Options=       ; connection options
  ServerPath=    ; absolute path to the mysqld executable,
                 ; defaults to /usr/sbin/mysqld, internal server only
  CleanServerShutdownCommand= ; a command to shutdown internal server cleanly
                              ; default is reasonable

* PostgreSQL backend provided by the akonadi-backend-postgresql package. Like
  MySQL backend, by default PostgreSQL backend starts an unpriviledged instance
  of the PostgreSQL server for each user. Alternatively, if you switch
  StartServer option off, you may specify an external PostgreSQL database to
  connect to.

  This backend uses QSql PSQL driver. The following configuration options are
  available:

  [%General]
  Driver=QPSQL

  [QPSQL]
  StartServer=   ; whether to start internal server instance, defaults to true
  Name=          ; dababase name
  Host=          ; name of host running external PostgreSQL server
  User=          ; database user, external server only
  Password=      ; database user password, external server only
  Options=       ; connection options
  ServerPath=    ; path to the pg_ctl executable, internal server only
  InitDbPath=    ; path to the initdb executable, internal server only
  CleanServerShutdownCommand= ; a command to shutdown internal server cleanly,
                              ; default is reasonable

* SQLite backend provided by the akonadi-backend-sqlite package. It uses
  embedded SQLite database hence it does not need a separate instance of the
  SQL server.

  This backend is based on the custom Qt SQLite3 driver which is
  also shipped in the backend package. The following configuration options are
  available:

  [%General]
  Driver=QSQLITE3

  [QSQLITE3]
  Name=     ; path to the database file
            ; defaults to $XDG_DATA_HOME/akonadi/akonadi.db

NOTE: environment variables are not expanded in option values. Option must not
be present in the configuration file in order for its default to have effect.

 -- Jonathan Riddell <jriddell@ubuntu.com>, Thu,  4 Aug 2016 14:55:23 +0100
