mirror of
https://github.com/jwinterm/modoboa.git
synced 2026-10-18 05:51:26 +02:00
Documentation refactor.
wip
This commit is contained in:
Antoine Nguyen
@@ -1,74 +0,0 @@
|
||||
Using the virtual machine
|
||||
*************************
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
A virtual machine with a ready-to-use Modoboa setup is available `here
|
||||
<http://modoboa.org/resources/modoboa.vmdk.bz2>`_. 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
|
||||
<http://en.wikipedia.org/wiki/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
|
||||
<http://qemu.org/>`_ 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://<ip_address>/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.
|
||||
================ ======== ============================================
|
||||
@@ -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
|
||||
<https://github.com/modoboa/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 <mail server hostname>
|
||||
|
||||
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 <http://www.virtualenv.org/en/latest/>`_ 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 <hostname of your server> --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
|
||||
<http://modoboa-amavis.readthedocs.org>`_ extension, use the
|
||||
``amavis:`` prefix. For example: ``--dburl
|
||||
default:<database url> amavis:<database url>``.
|
||||
|
||||
A database url should meet the following syntax
|
||||
``<mysql|postgres>://[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 <modoboa_user>
|
||||
> source <virtuenv_path>/bin/activate
|
||||
|
||||
The general procedure is as follows::
|
||||
|
||||
> pip install modoboa==<VERSION>
|
||||
> cd <modoboa_instance_dir>
|
||||
> 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.
|
||||
@@ -61,7 +61,6 @@ Additional resource
|
||||
:maxdepth: 2
|
||||
|
||||
additional/migrating
|
||||
additional/virtualmachine
|
||||
|
||||
*******************
|
||||
Contributing
|
||||
|
||||
Reference in New Issue
Block a user