From d55409b91df4acad6e40fcf1964401bd90ca9827 Mon Sep 17 00:00:00 2001 From: Antoine Nguyen Date: Fri, 23 Sep 2016 19:31:26 +0200 Subject: [PATCH] Documentation refactor. wip --- doc/additional/virtualmachine.rst | 74 ----------- doc/getting_started.rst | 203 ++++++++++++++++++++++++++++++ doc/index.rst | 1 - 3 files changed, 203 insertions(+), 75 deletions(-) delete mode 100644 doc/additional/virtualmachine.rst create mode 100644 doc/getting_started.rst diff --git a/doc/additional/virtualmachine.rst b/doc/additional/virtualmachine.rst deleted file mode 100644 index 471c2c418..000000000 --- a/doc/additional/virtualmachine.rst +++ /dev/null @@ -1,74 +0,0 @@ -Using the virtual machine -************************* - -Introduction -============ - -A virtual machine with a ready-to-use Modoboa setup is available `here -`_. It is composed of -the following components: - -* Debian 6.0 (squeeze) -* Modoboa and its prerequisites -* MySQL -* Postfix -* Dovecot -* nginx and gunicorn - -Actually, it is the result you obtain if you follow the official -documentation. - -The disk image is using the `VMDK -`_ format and is compressed using -bzip2. To decompress it, just run the following command:: - - $ bunzip2 modoboa.vmdk.bz2 - -If you can't use the vmdk format, you can use `qemu -`_ to convert it to another one. For example:: - - $ qemu-img convert modoboa.vmdk -O qcow2 modoboa.qcow2 - -Then, just use your prefered virtualization software (qemu, kvm, -virtualbox, etc.) to start the machine. You'll need to configure at -least one bridged network interface if you want to be able to play -with Modoboa, ie. your machine must be visible from your network. - -The default network interface of the machine (``eth0``) is configured -to use the DHCP protocol. - -Connect to the machine -====================== - -The following UNIX users are available if you want to connect to the system: - -===== ======== ==================== -Login Password Description -===== ======== ==================== -root demo the root user -demo demo an unpriviliged user -===== ======== ==================== - -To connect to Modoboa, first connect to the system and retrieve its -current network address like this:: - - $ /sbin/ifconfig eth0 - -Once you know its address, open a web browser and go to this url:: - - http:///admin/ - -You should see the login page. Here are the users available by default: - -================ ======== ============================================ -Login Password Capabitilies -================ ======== ============================================ -admin password Default super administrator. Can do anything - on the admin but can't access applications - -admin@demo.local admin Administrator of the domain *demo.local*. - Can administrater its domain and access to - applications. - -user@demo.local user Simple user. Can access to applications. -================ ======== ============================================ diff --git a/doc/getting_started.rst b/doc/getting_started.rst new file mode 100644 index 000000000..1c80da81c --- /dev/null +++ b/doc/getting_started.rst @@ -0,0 +1,203 @@ +############### +Getting started +############### + +************ +Installation +************ + +Using the installer +=================== + +If you start from scratch and want to deploy a complete mail server, +you will love the `modoboa installer +`_! It is the easiest +and the quickest way to setup a fully functional server (modooba, +postfix, dovecot, amavis and more) on one machine. + +.. warning:: + + For now, only Debian and CentOS based Linux distributions are + supported. We do our best to improve compatibility but if you use + another Linux or a UNIX system, you will have to install Modoboa + :ref:`by_hand`. + +To use it, just run the following commands in your terminal:: + + $ git clone https://github.com/modoboa/modoboa-installer + $ cd modoboa-installer + $ sudo ./run.py + +Wait a few minutes and you're done \o/ + +.. _by_hand: + +By hand +======= + +In case you already have a running server (postfix, dovecot, etc.) or +you want to build a multi-machine architecture, you can install +Modoboa manually. + +Since Modoboa is a web application written in Python, the procedure +can be splitted in two parts: installing the application and +installing a web server. + +Modoboa +------- + +Prepare the system +~~~~~~~~~~~~~~~~~~ + +First of all, we recommand the following context: + +* using a dedicated system user +* using a `virtualenv `_ to + install the application because it will isolate it (and its + dependencies) from the rest of your system + +The following example illustrates how to realize this (Debian like system):: + + > sudo apt-get install python-virtualenv python-pip + > sudo useradd modoboa + > sudo -i modoboa + > virtualenv env + (env)> source env/bin/activate + (env)> pip install -U pip + +FIXME: dépendances système pour compilation + +Then, install Modoboa:: + + (env)> pip install modoboa + +Database +~~~~~~~~ + +.. warning:: + + This documentation does not cover the installation of a database + server but only the setup of a functional database that Modoboa + will use. + +Thanks to Django, Modoboa is compatible with the following databases: + +* PostgreSQL +* MySQL / MariaDB +* SQLite + +Since the last one does not require particular actions, only the first +two ones are described. + +PostgreSQL +********** + +Install the corresponding Python binding:: + + (env)> pip install psycopg2 + +Then, create a user and a database:: + + > sudo -i postgres + > + +MySQL / MariaDB +*************** + +Install the corresponding Python binding:: + + (env)> pip install MySQL-Python + +Then, create a user and a database:: + + > mysqladmin -u root -p create modoboa + +Deploy an instance +~~~~~~~~~~~~~~~~~~ + +`modoboa-admin.py`, a command line tool, lets you deploy a +*ready-to-use* Modoboa site using only one instruction:: + + (env)> modoboa-admin.py deploy instance --collectstatic \ + --domain --dburl default:database-url + +.. note:: + + You can install additional extensions during the deploy process. To + do so, use the ``--extensions`` option which accepts a list of + names as argument (``--extensions ext1 ext2 ...``). If you want to + install all extensions, just use the ``all`` keyword like this + ``--extensions all``. + + If you choose to install extensions one at a time, you will have to + add their names in settings.py to ``MODOBOA_APPS``. Also ensure that + you have the line ``from modoboa_amavis.settings import *`` at the + end of this file. + + The list of available extensions can be found on the :doc:`index + page <../index>`. Instructions to install them are available on + each extensions page. + +.. note:: + + You can specify more than one database connection using the + ``--dburl`` option. Multiple connections are differentiated by a + prefix. + + The primary connection must use the ``default:`` prefix (as shown + in the example above). For the `amavis + `_ extension, use the + ``amavis:`` prefix. For example: ``--dburl + default: amavis:``. + + A database url should meet the following syntax + ``://[user:pass@][host:port]/dbname`` **OR** + ``sqlite:////full/path/to/your/database/file.sqlite``. + +The command will ask you a few questions, answer them and you're +done. You can now go to the :ref:`first_use` section. + +In case you need a **silent installation** (e.g. if you're using +Salt-Stack, Ansible or whatever), it's possible to supply the database +credentials as commandline arguments. + +You can consult the complete option list by running the following +command:: + + $ modoboa-admin.py help deploy + + + +******* +Upgrade +******* + +.. warning:: + + The new version you are going to install may need to modify your + database. Before you start, make sure to backup everything! + +Most of the time, upgrading your installation to a newer Modoboa +version only requires a few actions. In any case, you will need to +apply the general procedure first and then check if the version you +are installing requires specific actions. + +.. note:: + + In case you use a dedicated user and/or a virtualenv, do not forget to + use them:: + + > sudo -i + > source /bin/activate + +The general procedure is as follows:: + + > pip install modoboa== + > cd + > python manage.py migrate + > python manage.py collectstatic + +Once done, check if the version you are installing requires +:ref:`specific_upgrade_instructions`. + +Finally, restart your web server. diff --git a/doc/index.rst b/doc/index.rst index fa9ecd85a..381770048 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -61,7 +61,6 @@ Additional resource :maxdepth: 2 additional/migrating - additional/virtualmachine ******************* Contributing