Projects/PIM/Akonadi/Multi-Instance - Revision history

Cmollekopf at 17:14, 3 May 2013

2013-05-03T17:14:08Z

Vkrause: /* Akonadi Console */

2012-07-15T12:32:11Z

‎Akonadi Console

Vkrause: akonadiconsole can now auto-detect the multi-instance setup

2012-07-15T11:23:05Z

akonadiconsole can now auto-detect the multi-instance setup

Cmollekopf: /* Development */

2012-07-13T07:42:59Z

‎Development

Cmollekopf at 08:41, 11 July 2012

2012-07-11T08:41:45Z

Cmollekopf at 16:22, 10 July 2012

2012-07-10T16:22:12Z

Cmollekopf: /* Missing Features */

2012-07-10T16:05:17Z

‎Missing Features

Cmollekopf: Created page with "== Akonadi Multi-Instance Setup == The multi-instance akonadi setup allows to run multiple akonadi-servers in parallel, using the same posix-user. DBus service names are postfix..."

2012-07-10T15:55:41Z

Created page with "== Akonadi Multi-Instance Setup == The multi-instance akonadi setup allows to run multiple akonadi-servers in parallel, using the same posix-user. DBus service names are postfix..."

New page

== Akonadi Multi-Instance Setup ==

The multi-instance akonadi setup allows to run multiple akonadi-servers in parallel, using the same posix-user. DBus service names are postfixed with an instance identifier, so multiple instances can run on the same DBus.
Also all relevant configuration files/direcories are either postfixed or put in a separate directory, to avoid any clashes, making it safe to run multiple instances in parallel.

The behavior of a normal akonadi instance is not changed.

To run multiple akonadi instances in parallel it is required to assign to each instance a unique identifier using:
<pre>
akonadictl --identifier IDENTIFIER start
</pre>

You can run a normal akonadi instance (without --identifier) in parallel with multi-instance akonadi instances.

Each instance will run it's own mysql server.

=== Directories ===
The multi-instance setup puts it's files in the following directories:
* .config/akonadi/instance/$IDENTIFIER
* .local/share/akonadi/instance/$IDENTIFIER
* .kde4/share/config/akonadi/akonadi_imap_resource_0_$IDENTIFIERrc

To cleanup an instance, just delete all the directories and configs above.

=== Akonadiconsole ===

To connect to an instance using akonadiconsole export the following environment variable first (with inst1 being the instance identifier):
<pre>
export AKONADI_INSTANCE=inst1
</pre>

A couple of features, such as the debugging facilities or the mysql console do not work, but managing agents and browsing the collection tree should work just fine.
Note that you might get an error message on startup that your mysql database socket couldn't be found, this is safe to ignore.

You can connect to the mysql instance directly using the mysql console (standalone, not the akonadiconsole one):
<pre>
mysql --protocol=SOCKET --socket=.local/share/akonadi/instance/inst1/socket-myhost2/mysql.socket
</pre>

=== Missing Features ===
* Debugging facilities as mentioned above
* Firstrun: This must be disabled by exporting AKONADI_DISABLE_AGENT_AUTOSTART, otherwise the firstrun code will crash (an assert prevents running the code since it is unsafe so far).

=== Development ===
In order to make akonadi code work in the multi-instance setup all unique identifiers need to be made distinguishable between instances. That includes most prominently:
* dbus service names
* configfile names
* default directory paths

You only need to change these, if you add/use dbus interfaces, or access configfiles directly. Most things have already been taken care of using the agentbase/resourcebase classes.

* kdepimlibs/akonad/servermanager.h contains a couple of helper functions to help with that.

← Older revision		Revision as of 17:14, 3 May 2013
Line 1:		Line 1:
		+	{{warning\|This does not yet work with any akonadi agents/resource as they need to be ported first (only akonadiconsole has been ported so far). Don't use it unless you know what you're doing.}}
		+
	== Akonadi Multi-Instance Setup ==		== Akonadi Multi-Instance Setup ==

@@ Line 54: / Line 54: @@
 Unlike regular client applications, ''akonadiconsole'' will automatically detect the presence of multiple Akonadi instances and asks to which one to connect to if more than one was found.
-A couple of features, such as the debugging facilities or the Mysql console do not work yet, but managing agents and browsing the collection tree should work just fine.
+Some of the debugging facilities do not work correctly yet, these are the known issues:
-Note that you might get an error message on startup that your Mysql database socket couldn't be found, this is safe to ignore.
+* Raw socket always connects to the main instance.
-You can connect to the Mysql instance directly using the Mysql console (standalone, not the akonadiconsole one):
+You can also connect to the Mysql instance directly using the Mysql console (standalone, not the akonadiconsole one):
 <pre>
 mysql --protocol=SOCKET --socket=~/.local/share/akonadi/instance/<inst1>/socket-<hostname>/mysql.socket

@@ Line 1: / Line 1: @@
 == Akonadi Multi-Instance Setup ==
-The multi-instance akonadi setup allows to run multiple akonadi-servers in parallel, using the same posix-user. DBus service names are postfixed with an instance identifier, so multiple instances can run on the same DBus.
+The multi-instance Akonadi setup allows to run multiple Akonadi servers in parallel, using the same posix-user and D-Bus session bus. D-Bus service names are postfixed with an instance identifier and  all relevant configuration files/directories are either postfixed or put in a separate directory, to avoid any clashes, making it safe to run multiple instances in parallel.
-Also all relevant configuration files/direcories are either postfixed or put in a separate directory, to avoid any clashes, making it safe to run multiple instances in parallel.
-The behavior of a normal akonadi instance is not changed.
+The behavior of a normal Akonadi instance is not changed.
-To run multiple akonadi instances in parallel it is required to assign to each instance a unique identifier using:
+To run multiple Akonadi instances in parallel it is required to assign to each instance a unique identifier using:
 <pre>
 akonadictl --instance IDENTIFIER start
 </pre>
-An application will the connect to a server depending on the AKONADI_INSTANCE environment variable (set to IDENTIFIER).
+An application will then connect to a server depending on the AKONADI_INSTANCE environment variable (set to IDENTIFIER).
-You can run a normal akonadi instance (without --instance) in parallel with multi-instance akonadi instances.
+You can run a normal Akonadi instance (without --instance) in parallel with multi-instance Akonadi instances.
-Each instance will run it's own mysql server.
+Each instance will run it's own Mysql server by default, just like a regular Akonadi instance does.
 == Usage ==
@@ Line 24: / Line 23: @@
 </pre>
-connect akonadiconsole:
+connect any Akonadi client (see also risks section below):
 <pre>
 export AKONADI_INSTANCE=IDENTIFIER
@@ Line 44: / Line 43: @@
 To cleanup an instance, just delete all the directories and configs above.
-=== Akonadiconsole ===
+=== Akonadi Clients ===
-To connect to an instance using akonadiconsole export the following environment variable first (with inst1 being the instance identifier):
+To connect to an instance using a Akonadi client application, export the following environment variable first (with inst1 being the instance identifier):
 <pre>
 export AKONADI_INSTANCE=inst1
 </pre>
-A couple of features, such as the debugging facilities or the mysql console do not work, but managing agents and browsing the collection tree should work just fine.
+=== Akonadi Console ===
-Note that you might get an error message on startup that your mysql database socket couldn't be found, this is safe to ignore.
-You can connect to the mysql instance directly using the mysql console (standalone, not the akonadiconsole one):
+Unlike regular client applications, ''akonadiconsole'' will automatically detect the presence of multiple Akonadi instances and asks to which one to connect to if more than one was found.
 <pre>
-mysql --protocol=SOCKET --socket=.local/share/akonadi/instance/inst1/socket-myhost2/mysql.socket
+mysql --protocol=SOCKET --socket=~/.local/share/akonadi/instance/<inst1>/socket-<hostname>/mysql.socket
 </pre>
-=== Missing Features ===
+=== Risks and Missing Features ===
-* Debugging facilities as mentioned above
+* Debugging facilities in akonadiconsole as mentioned above
 * Firstrun: Is disabled in servermanager.cpp, otherwise the firstrun code will crash (an assert prevents running the code since it is unsafe so far).
 * It is not safe to run a multi-instance setup without exporting AKONADI_DISABLE_AGENT_AUTOSTART first, because the default setup desktop files contain configs with hardcoded paths, which would result in every akonadi instance creating a resource for the same default path.
 === Development ===
-In order to make akonadi code work in the multi-instance setup all unique identifiers need to be made distinguishable between instances. That includes most prominently:
+In order to make Akonadi code work in the multi-instance setup all unique identifiers need to be made distinguishable between instances. That includes most prominently:
-* dbus service names
+* D-Bus service names
-* configfile names
+* configuration file names
 * default directory paths
-You only need to change these, if you add/use dbus interfaces, or access configfiles directly. Most things have already been taken care of using the agentbase/resourcebase classes.
+You only need to change these, if you add/use D-Bus interfaces, or access configuration files directly. Most things have already been taken care of using the AgentBase/ResourceBase classes.
 * kdepimlibs/akonadi/servermanager.h contains a couple of helper functions to help with that.
-Note that it is not possible to change the dbus names or the prefixed directories just in kdepimlibs, as the akonadi-server makes assumptions on where to find the directories and dbus-services.
+Note that it is not possible to change the D-Bus names or the prefixed directories just in kdepimlibs, as the Akonadi server makes assumptions on where to find the directories and D-Bus services.

← Older revision		Revision as of 07:42, 13 July 2012
Line 72:		Line 72:
	You only need to change these, if you add/use dbus interfaces, or access configfiles directly. Most things have already been taken care of using the agentbase/resourcebase classes.		You only need to change these, if you add/use dbus interfaces, or access configfiles directly. Most things have already been taken care of using the agentbase/resourcebase classes.

−	* kdepimlibs/~~akonad~~/servermanager.h contains a couple of helper functions to help with that.	+	* kdepimlibs/akonadi/servermanager.h contains a couple of helper functions to help with that.
		+
		+	Note that it is not possible to change the dbus names or the prefixed directories just in kdepimlibs, as the akonadi-server makes assumptions on where to find the directories and dbus-services.

@@ Line 8: / Line 8: @@
 To run multiple akonadi instances in parallel it is required to assign to each instance a unique identifier using:
 <pre>
-akonadictl --identifier IDENTIFIER start
+akonadictl --instance IDENTIFIER start
 </pre>
 An application will the connect to a server depending on the AKONADI_INSTANCE environment variable (set to IDENTIFIER).
-You can run a normal akonadi instance (without --identifier) in parallel with multi-instance akonadi instances.
+You can run a normal akonadi instance (without --instance) in parallel with multi-instance akonadi instances.
 Each instance will run it's own mysql server.
@@ Line 21: / Line 21: @@
 <pre>
 export AKONADI_DISABLE_AGENT_AUTOSTART
-akonadictl --identifier IDENTIFIER start
+akonadictl --instance IDENTIFIER start
 </pre>
@@ Line 32: / Line 32: @@
 stop instance:
 <pre>
-akonadictl --identifier IDENTIFIER stop
+akonadictl --instance IDENTIFIER stop
 </pre>