diff --git a/doc/extending/events.rst b/doc/extending/events.rst index ac6d4b75a..a55518d9c 100644 --- a/doc/extending/events.rst +++ b/doc/extending/events.rst @@ -47,6 +47,396 @@ Read further to get a complete list and description of all available events. Supported events **************** +AccountCreated +============== + +Raised when a new account is created. + +*Callback prototype*:: + + def callback(account): pass + +* ``account`` is the newly created account (``User`` instance) + +AccountDeleted +============== + +Raised when an existing account is deleted. + +*Callback prototype*:: + + def callback(account): pass + +* ``oldaccount`` is the account that is going to be deleted + +AccountModified +=============== + +Raised when an existing account is modified. + +*Callback prototype*:: + + def callback(oldaccount, newaccount): pass + +* ``oldaccount`` is the account before it is modified + +* ``newaccount`` is the account after the modification + +AdminMenuDisplay +================ + +Raised when an admin menu is about to be displayed. + +*Callback prototype*:: + + def callback(target, user): pass + +The ``target`` argument indicates which menu is being +displayed. Possible values are: + +* ``admin_menu_box`` : corresponds to the menu bar available inside administration pages +* ``top_menu`` : corresponds to the top black bar + +See :ref:`usermenudisplay` for a description of what callbacks that +listen to this event must return. + +CanCreate +========= + +Raised just before a user tries to create a new object. + +*Callback prototype*:: + + def callback(user): pass + +* ``user`` is a ``User`` instance + +Return ``True`` or ``False`` to indicate if this user can respectively +create or not create a new ``Domain`` object. + +CheckExtraAccountForm +===================== + +When an account is being modified, this event lets extensions check if +this account is concerned by a specific form. + +*Callback prototype*:: + + def callback(account, form): pass + +* ``account`` is the ``User`` instance beeing modified + +* ``form`` is a dictionnary (same content as for ``ExtraAccountForm``) + +Callbacks listening to this event must return a list containing one +Boolean. + +CreateDomain +============ + +Raised when a new domain is created. + +*Callback prototype*:: + + def callback(user, domain): pass + +* ``user`` corresponds to the ``User`` object creating the domain (its owner) +* ``domain`` is a ``Domain`` instance + +CreateMailbox +============= + +Raised when a new mailbox is created. + +*Callback prototype*:: + + def callback(user, mailbox): pass + +* ``user`` is the new mailbox's owner (``User`` instance) +* ``mailbox`` is the new mailbox (``Mailbox`` instance) + +DeleteDomain +============ + +Raised when an existing domain is about to be deleted. + +*Callback prototype*:: + + def callback(domain): pass + +* ``domain`` is a ``Domain`` instance + +DeleteMailbox +============= + +Raised when an existing mailbox is about to be deleted. + +*Callback prototype*:: + + def callback(mailbox): pass + +* ``mailbox`` is a ``Mailbox`` instance + +DomainAliasCreated +================== + +Raised when a new domain alias is created. + +*Callback prototype*:: + + def callback(user, domain_alias): pass + +* ``user`` is the new domain alias owner (``User`` instance) +* ``domain_alias`` is the new domain alias (``DomainAlias`` instance) + +DomainAliasDeleted +================== + +Raised when an existing domain alias is about to be deleted. + +*Callback prototype*:: + + def callback(domain_alias): pass + +* ``domain_alias`` is a ``DomainAlias`` instance + +ExtDisabled +=========== + +Raised just after an extension has been disabled. + +*Callback prototype*:: + + def callback(extension): pass + +* ``extension`` is an ``Extension`` instance + +ExtEnabled +========== + +Raised just after an extension has been activated. + +*Callback prototype*:: + + def callback(extension): pass + +* ``extension`` is an ``Extension`` instance + +ExtraAccountForm +================ + +Let extensions add new forms to the account edition form (the one with +tabs). + +*Callback prototype*:: + + def callback(user, account): pass + +* ``user`` is a ``User`` instance corresponding to the currently + logged in user + +* ``account`` is the account beeing modified (``User`` instance) + +Callbacks listening to the event must return a list of dictionnaries, +each one must contain at least three keys:: + + {"id" : "", + "title" : "", + "cls" : TheFormClassName} + +ExtraAdminContent +================= + +Let extensions add extra content into the admin panel. + +*Callback prototype*:: + + def callback(user, target, currentpage): pass + +* ``user`` is a ``User`` instance corresponding to the currently + logged in user + +* ``target`` is a string indicating the place where the content will + be displayed. Possible values are : ``leftcol`` + +* ``currentpage`` is a string indicating which page (or section) is + displayed. Possible values are : ``domains``, ``identities`` + +Callbacks listening to this event must return a list of string. + +ExtraDomainForm +=============== + +Let extensions add new forms to the domain edition form (the one with +tabs). + +*Callback prototype*:: + + def callback(user, domain): pass + +* ``user`` is a ``User`` instance corresponding to the currently + logged in user + +* ``domain`` is the domain beeing modified (``Domain`` instance) + +Callbacks listening to the event must return a list of dictionnaries, +each one must contain at least three keys:: + + {"id" : "", + "title" : "", + "cls" : TheFormClassName} + +FillAccountInstances +==================== + +When an account is beeing modified, this event is raised to fill extra +forms. + +*Callback prototype*:: + + def callback(user, account, instances): pass + +* ``user`` is a ``User`` instance corresponding to the currently + logged in user + +* ``account`` is the ``User`` instance beeing modified + +* ``instances`` is a dictionnary where the callback will add + information needed to fill a specific form + +FillDomainInstances +=================== + +When a domain is beeing modified, this event is raised to fill extra +forms. + +*Callback prototype*:: + + def callback(user, domain, instances): pass + +* ``user`` is a ``User`` instance corresponding to the currently + logged in user + +* ``domain`` is the ``Domain`` instance beeing modified + +* ``instances`` is a dictionnary where the callback will add + information needed to fill a specific form + +GetAnnouncement +=============== + +Some places in the interface let plugins add their own announcement +(ie. message). + +*Callback prototype*:: + + def callback(target): pass + +* ``target`` is a string indicating the place where the announcement + will appear: + +* ``loginpage`` : corresponds to the login page + +Callbacks listening to this event must return a list of string. + +.. _getextraroles: + +GetExtraRoles +============= + +Let extensions define new administrative roles. + +*Callback prototype*:: + + def callback(user): pass + +* ``user`` is a ``User`` instance corresponding to the currently + logged in user + +Callbacks listening to this event must return a list of 2uple (two +strings) which respect the following format: ``(value, label)``. + +GetStaticContent +================ + +Let extensions add static content (ie. CSS or javascript) to default +pages. It is pretty useful for functionalities that don't need a +template but need javascript stuff. + +*Callback prototype*:: + + def callback(user): pass + +* ``user`` is a ``User`` instance corresponding to the currently + logged in user + +Callbacks listening to this event must return a list of string. + +MailboxAliasCreated +=================== + +Raised when a new mailbox alias is created. + +*Callback prototype*:: + + def callback(user, mailbox_alias): pass + +* ``user`` is the new domain alias owner (``User`` instance) +* ``mailbox_alias`` is the new mailbox alias (``Alias`` instance) + +MailboxAliasDeleted +=================== + +Raised when an existing mailbox alias is about to be deleted. + +*Callback prototype*:: + + def callback(mailbox_alias): pass + +* ``mailbox_alias`` is an ``Alias`` instance + +ModifyMailbox +============= + +Raised when an existing mailbox is modified. + +*Callback prototype*:: + + def callback(newmailbox, oldmailbox): pass + +* ``newmailbox`` is a ``Mailbox`` instance containing the new values +* ``oldmailbox`` is a ``Mailbox`` instance containing the old values + +PasswordChange +============== + +Raised just before a *password change* action. + +*Callback prototype*:: + + def callback(user): pass + +* ``user`` is a ``User`` instance + +Callbacks listening to this event must return a list containing either +``True`` or ``False``. If at least one ``True`` is returned, the +*password change* will be cancelled (ie. changing the password for +this user is disabled). + +TopNotifications +================ + +Let extensions add custom content into the top bar. + +*Callback prototype*:: + + def callback(user): pass + +* ``user`` is a ``User`` instance corresponding to the currently + logged in user + +Callbacks listening to this event must return a list of string. + UserLogin ========= @@ -79,9 +469,10 @@ Raised when a user menu is about to be displayed. The ``target`` argument indicates which menu is being displayed. Possible values are: -* ``uprefs_menu`` : corresponds to the menu bar available inside the +* ``options_menu``: corresponds to the top-right user menu +* ``uprefs_menu``: corresponds to the menu bar available inside the *User preferences* page -* ``top_menu`` : corresponds to the top blue bar +* ``top_menu``: corresponds to the top black bar All the callbacks that listen to this event must return a list of dictionnaries (corresponding to menu entries). Each dictionnary must @@ -89,355 +480,4 @@ contain at least the following keys:: {"name" : "a_name_without_spaces", "label" : _("The menu label"), - "url" : reverse("your_view"), # can be set to "" - "img" : static_url("your_pic")} # can be set to "" - -AdminMenuDisplay -================ - -Raised when an admin menu is about to be displayed. - -*Callback prototype*:: - - def callback(target, user): pass - -The ``target`` argument indicates which menu is being -displayed. Possible values are: - -* ``admin_menu_box`` : corresponds to the menu bar available inside administration pages -* ``top_menu`` : corresponds to the *Admin* dropdown menu located inside the top blue bar - -See :ref:`usermenudisplay` for a description of what callbacks that -listen to this event must return. - -GetStaticContent -================ - -Let extensions add static content (ie. CSS or javascript) to default -pages. It is pretty useful for functionalities that don't need a -template but need javascript stuff. - -*Callback prototype*:: - - def callback(user): pass - -* ``user`` is a ``User`` instance corresponding to the currently - logged in user - -Callbacks listening to this event must return a list of string. - -CanCreate -========= - -Raised just before a user tries to create a new object. - -*Callback prototype*:: - - def callback(user): pass - -* ``user`` is a ``User`` instance - -Return ``True`` or ``False`` to indicate if this user can respectively -create or not create a new ``Domain`` object. - -CreateDomain -============ - -Raised when a new domain is created. - -*Callback prototype*:: - - def callback(user, domain): pass - -* ``user`` corresponds to the ``User`` object creating the domain (its owner) -* ``domain`` is a ``Domain`` instance - -DeleteDomain -============ - -Raised when an existing domain is about to be deleted. - -*Callback prototype*:: - - def callback(domain): pass - -* ``domain`` is a ``Domain`` instance - -DomainAliasCreated -================== - -Raised when a new domain alias is created. - -*Callback prototype*:: - - def callback(user, domain_alias): pass - -* ``user`` is the new domain alias owner (``User`` instance) -* ``domain_alias`` is the new domain alias (``DomainAlias`` instance) - -DomainAliasDeleted -================== - -Raised when an existing domain alias is about to be deleted. - -*Callback prototype*:: - - def callback(domain_alias): pass - -* ``domain_alias`` is a ``DomainAlias`` instance - -CreateMailbox -============= - -Raised when a new mailbox is created. - -*Callback prototype*:: - - def callback(user, mailbox): pass - -* ``user`` is the new mailbox's owner (``User`` instance) -* ``mailbox`` is the new mailbox (``Mailbox`` instance) - -DeleteMailbox -============= - -Raised when an existing mailbox is about to be deleted. - -*Callback prototype*:: - - def callback(mailbox): pass - -* ``mailbox`` is a ``Mailbox`` instance - -ModifyMailbox -============= - -Raised when an existing mailbox is modified. - -*Callback prototype*:: - - def callback(newmailbox, oldmailbox): pass - -* ``newmailbox`` is a ``Mailbox`` instance containing the new values -* ``oldmailbox`` is a ``Mailbox`` instance containing the old values - -MailboxAliasCreated -=================== - -Raised when a new mailbox alias is created. - -*Callback prototype*:: - - def callback(user, mailbox_alias): pass - -* ``user`` is the new domain alias owner (``User`` instance) -* ``mailbox_alias`` is the new mailbox alias (``Alias`` instance) - -MailboxAliasDeleted -=================== - -Raised when an existing mailbox alias is about to be deleted. - -*Callback prototype*:: - - def callback(mailbox_alias): pass - -* ``mailbox_alias`` is an ``Alias`` instance - -AccountCreated -============== - -Raised when a new account is created. - -*Callback prototype*:: - - def callback(account): pass - -* ``account`` is the newly created account (``User`` instance) - -AccountModified -=============== - -Raised when an existing account is modified. - -*Callback prototype*:: - - def callback(oldaccount, newaccount): pass - -* ``oldaccount`` is the account before it is modified - -* ``newaccount`` is the account after the modification - -AccountDeleted -============== - -Raised when an existing account is deleted. - -*Callback prototype*:: - - def callback(account): pass - -* ``oldaccount`` is the account that is going to be deleted - -ExtraAccountForm -================ - -Let extensions add new forms to the global account edition form (the -one with tabs). - -*Callback prototype*:: - - def callback(user, account): pass - -* ``user`` is a ``User`` instance corresponding to the currently - logged in user - -* ``account`` is the account beeing modified (``User`` instance) - -Callbacks listening to the event must return a list of dictionnaries, -each one must contain at least three keys:: - - {"id" : "", - "title" : "", - "cls" : TheFormClassName} - -CheckExtraAccountForm -===================== - -When an account is being modified, this event lets extensions check if -this account is concerned by a specific form. - -*Callback prototype*:: - - def callback(account, form): pass - -* ``account`` is the ``User`` instance beeing modified - -* ``form`` is a dictionnary (same content as for ``ExtraAccountForm``) - -Callbacks listening to this event must return a list containing one -Boolean. - -FillAccountInstances -==================== - -When an account is beeing modified, this event is raised to fill extra -forms. - -*Callback prototype*:: - - def callback(user, account, instances): pass - -* ``user`` is a ``User`` instance corresponding to the currently - logged in user - -* ``account`` is the ``User`` instance beeing modified - -* ``instances`` is a dictionnary where the callback will add - information needed to fill a specific form - -.. _getextraroles: - -GetExtraRoles -============= - -Let extensions define new administrative roles. - -*Callback prototype*:: - - def callback(user): pass - -* ``user`` is a ``User`` instance corresponding to the currently - logged in user - -Callbacks listening to this event must return a list of 2uple (two -strings) which respect the following format: ``(value, label)``. - -ExtEnabled -========== - -Raised just after an extension has been activated. - -*Callback prototype*:: - - def callback(extension): pass - -* ``extension`` is an ``Extension`` instance - -ExtDisabled -=========== - -Raised just after an extension has been disabled. - -*Callback prototype*:: - - def callback(extension): pass - -* ``extension`` is an ``Extension`` instance - -GetAnnouncement -=============== - -Some places in the interface let plugins add their own announcement -(ie. message). - -*Callback prototype*:: - - def callback(target): pass - -* ``target`` is a string indicating the place where the announcement - will appear: - -* ``loginpage`` : corresponds to the login page - -Callbacks listening to this event must return a list of string. - -TopNotifications -================ - -Let extensions add custom content into the top bar. - -*Callback prototype*:: - - def callback(user): pass - -* ``user`` is a ``User`` instance corresponding to the currently - logged in user - -Callbacks listening to this event must return a list of string. - -ExtraAdminContent -================= - -Let extensions add extra content into the admin panel. - -*Callback prototype*:: - - def callback(user, target, currentpage): pass - -* ``user`` is a ``User`` instance corresponding to the currently - logged in user - -* ``target`` is a string indicating the place where the content will - be displayed. Possible values are : ``leftcol`` - -* ``currentpage`` is a string indicating which page (or section) is - displayed. Possible values are : ``domains``, ``identities`` - -Callbacks listening to this event must return a list of string. - -PasswordChange -============== - -Raised just before a *password change* action. - -*Callback prototype*:: - - def callback(user): pass - -* ``user`` is a ``User`` instance - -Callbacks listening to this event must return a list containing either -``True`` or ``False``. If at least one ``True`` is returned, the -*password change* will be cancelled (ie. changing the password for -this user is disabled). + "url" : reverse("your_view")} diff --git a/doc/getting_started/configuration.rst b/doc/getting_started/configuration.rst index bdfa2dae5..60aad1bc3 100644 --- a/doc/getting_started/configuration.rst +++ b/doc/getting_started/configuration.rst @@ -86,6 +86,8 @@ manipulate directories in vmail's homedir. To do so, edit the ALL=(vmail) NOPASSWD: ALL +.. _timezone_lang: + ********************** Time zone and language ********************** diff --git a/doc/getting_started/install.rst b/doc/getting_started/install.rst index ada6dc093..4adacb965 100644 --- a/doc/getting_started/install.rst +++ b/doc/getting_started/install.rst @@ -16,10 +16,7 @@ Requirements * `rrdtool python binding `_ * `sievelib python module `_ -Optional -======== - -* `ckeditor version 3.4.1+ `_ +.. _get_modoboa: *********** Get Modoboa @@ -51,13 +48,14 @@ Database Thanks to *django*, Modoboa supports several databases. Depending on the one you will use, you must install the appropriate python package: -* `MySQL `_: `mysqldb `_ -* `PostgreSQL `_ : `psycopg2 `_ -* `SQLite `_: already shipped with *Python* +* `mysqldb `_ for `MySQL `_ +* `psycopg2 `_ for `PostgreSQL `_ Then, create a user and a database that will be used by Modoboa. Make sure your database is using UTF8 as a default charset. +.. _deployment: + ********** Deployment ********** @@ -91,5 +89,15 @@ available: * Username: ``admin`` * Password: ``password`` -It is **strongly** recommanded to change this password the first time +It is **strongly** recommended to change this password the first time you log into Modoboa. + +To check if your installation works, just launch the embedded HTTP +server:: + + $ python manage.py runserver + +You should be able to access your site at http://locahost:8000/. + +For a production environnement, we recommend using a stable webserver +like :ref:`apache2` or :ref:`nginx-label`. diff --git a/doc/getting_started/plugins.rst b/doc/getting_started/plugins.rst index ffdf3851a..96daf57df 100644 --- a/doc/getting_started/plugins.rst +++ b/doc/getting_started/plugins.rst @@ -29,6 +29,8 @@ to domain administrators. If you don't want to limit a particular object type, just set the associated value to -1. +.. _amavis_frontend: + ******************** Amavisd-new frontend ******************** @@ -171,6 +173,8 @@ Here is a link example:: http:///quarantine/%i/?rcpt=%R&secret_id=[:secret_id] +.. _stats: + ******************** Graphical statistics ******************** @@ -207,6 +211,8 @@ Replace ```` with the path of your Modoboa instance. Graphics will be automatically created after each parsing. +.. _postfix_ar: + *************************** Postifx auto-reply messages *************************** @@ -323,11 +329,18 @@ The size of each attachment sent with messages is limited. You can change the default value by modifying the ``MAX_ATTACHMENT_SIZE`` parameter. -Using a rich editor -=================== +Using CKeditor +============== -CKeditor is supported by Modoboa. To use it, first download it from -`the official website `_, then extract the tarball:: +Modoboa supports CKeditor to compose HTML messages. To use it, first +download it from `the official website `_, then +extract the tarball:: $ cd - $ + $ tar xzf /path/to/ckeditor/tarball.tag.gz -C sitestatic/js/ + +And you're done! + +Now, each user has the possibility to choose between CKeditor and the +raw text editor to compose their messages. (see *User > Settings > +Preferences > Webmail*) diff --git a/doc/getting_started/upgrade.rst b/doc/getting_started/upgrade.rst index 04a94d514..d2681d2e0 100644 --- a/doc/getting_started/upgrade.rst +++ b/doc/getting_started/upgrade.rst @@ -5,24 +5,59 @@ Upgrading an existing installation This section regroups all the upgrade procedures required to use newest versions of Modoboa. +.. note:: + Before running a migration, we recommend that you make + a copy of your existing database. + ************** Latest version ************** -FIXME +Starting with version 0.9.1, Modoboa comes as a standard django +application. Fetch the latest version (see :ref:`get_modoboa`) and +install it. -************** -Modoboa <= 0.9 -************** +``pip`` users, just run the following command:: + + $ pip install --upgrade modoboa + +Then, follow the common procedure:: + + $ cd + $ python manage.py syncdb --migrate + $ python collectstatic + +Finally, refer to this page to see if the version you're installing +requires specific operations. + +0.9.1: standard django application and more +=========================================== + +For this version, we recommend to install a new instance (see +:ref:`deployment`) in a different directory. + +Then, copy the following content from the old installation to the new +one: + +* The ``media`` directory +* The directory containing RRD files if you use the :ref:`stats` plugin + +Don't copy the old *settings.py* file, just keep the new one and +modify it (see :ref:`database` and :ref:`timezone_lang`). + +Finally, check the :ref:`amavis_frontend`, :ref:`postfix_ar` and +:ref:`stats` chapters (depending on those you use) because the +provided cron scripts have been changed, you must update the way you +call them. + +******************** +Modoboa prior to 0.9 +******************** First, decompress the new tarball at the same location than your current installation. Then, check if the new version you're installing requires a migration. -.. note:: - Before executing a schema/data migration, I recommend that you make - a copy of your existing database. - 0.9: global UI refactoring, new *limits* extension and more =========================================================== diff --git a/doc/integration/web_servers.rst b/doc/integration/web_servers.rst index 6bcfa3e69..100a585e8 100644 --- a/doc/integration/web_servers.rst +++ b/doc/integration/web_servers.rst @@ -36,6 +36,8 @@ following inside:: This is one possible configuration. Note that you will certainly need more configuration in order to launch Apache. +.. _nginx-label: + ***** Nginx *****