self-hosted/Mailu
1
0
Fork 0
mirror of https://github.com/Mailu/Mailu.git synced 2025-11-23 22:04:47 +02:00
Code Issues Releases Activity

Add a proper INSTALL documentation

Browse Source
This commit is contained in:
Pierre Jaury
2016-06-12 11:32:42 +02:00
parent 45200b886b
commit 37cae069ea
3 changed files with 249 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
INSTALL.md Normal file
View File

@@ -0,0 +1,206 @@
Installing Freeposte.io
=======================
Things to consider
==================
Freeposte.io is working, it has been powering hundreds of e-mail accounts
since around January 2016. It is still not massively tested however and
you should not run any critical mail server until you have properly tested
every feature.
Also, the idea behind Freeposte.io is based on the work by folks from Poste.io.
If free software is not the reason you chose Freeposte.io or if you are seeking
long-term professional support, you should probably turn to them instead.
Picking a distribution
======================
The mail server runs as a set of Docker containers. It is thus almost agnostic
of the underlying operating system as long as a fairly recent Linux kernel is
running and the Docker API (>= 1.11) is available.
Because most of our tests run on Debian Jessie and Debian Stretch, we recommend
one of these for the base system. Freeposte.io should however be able to run on
any of the [officially supported distributions](https://docs.docker.com/engine/installation/).
For the purpose of this guide, all examples are based on Debian Stretch. The
differences with other system will hardly be noticeable however.
Setting up the distribution
===========================
First, install Debian Stretch from the *netinstall* CD image. When installing,
make sure that you either:
- setup a root *ext4* partition,
- or setup a root *btrfs* partition,
- or leave enough unpartitionned space for a dedicated *ext4* or *btrfs*
partition.
If you chose to create a dedicated partition, simply mount it to
``/var/lib/docker``. You could also create a separate partition (*ext4* is a
sane default) ans mount it to ``/freeposte`` for storing e-mail data.
Docker supports *AUFS* over *ext4* and *btrfs* as stable storage drivers.
Other filesystems are supported such as *OverlayFS*. If you know what you are
doing, you should go for it.
Freeposte uses Docker port forwarding from the host to make services available
to external users. First, your host should have a public IP address configured
(see ``/etc/network/interfaces``) or your router should forward connections
to its internal IP address. Due to spam problems and reputation services, it
is highly recommended that you use a dedicated IP address for your mail server
and that you have a dedicated hostname with forward and reverse DNS entries
for this IP address.
Also, your host must not listen on ports ``25``, ``80``, ``110``, ``143``,
``443``, ``465``, ``587``, ``993`` or ``995`` as these are used by Freeposte
services. Therefore, you should disable or uninstall any program that is
listening on these ports (or have them listen on a different port). For
instance, on a default Debian install:
```
apt-get autoremove --purge exim4 exim4-base
```
Finally, Docker relies heavily on ``iptables`` for port forwardings. You
should use ``iptables-persistent`` (or any equivalent tool on other
systems) for managing persistent rules. If you were brave enough to switch to
``nftables``, you will have to rollback until official support is released
by Docker or setup your own rulesets.
Setting up Docker
=================
Freeposte relies on some of the latest Docker features. Therefore, you should
install Docker from the official repositories instead of your distribution
ones.
The Docker website is full of [detailed instructions](https://docs.docker.com/engine/installation/)
about setting up a proper Docker install. Default configuration should be
suited for Freeposte.
Additionally, you must install ``docker-compose`` by following the instructions
from the [Docker website](https://docs.docker.com/compose/). Compose is a
management tool for Docker, especially suited for multipl containers systems
like Freeposte.
Once everything is setup, you should be able to run the following commands
(exact version numbers do not matter):
```
$ docker version
Client:
Version: 1.11.2
API version: 1.23
Go version: go1.6.2
Git commit: b9f10c9
Built: Sun Jun 5 23:17:55 2016
OS/Arch: linux/amd64
Server:
Version: 1.11.1
API version: 1.23
Go version: go1.6.2
Git commit: 5604cbe
Built: Mon May 2 00:06:51 2016
OS/Arch: linux/amd64
$ docker-compose version
docker-compose version 1.7.1, build 6c29830
docker-py version: 1.8.1
CPython version: 3.5.1
OpenSSL version: OpenSSL 1.0.2h 3 May 2016
```
Preparing the mail server environment
=====================================
Freeposte will store all of its persistent data in ``/freeposte`` by default,
simply create the directory and move there:
```
mkdir /freeposte
cd /freeposte
```
Docker Compose configuration is stored in a file named ``docker-compose.yml``.
Additionally, Freeposte relies on an environment file for various settings.
Download the templates files from the git repository:
```
wget https://raw.githubusercontent.com/kaiyou/freeposte.io/master/docker-compose.yml
wget https://raw.githubusercontent.com/kaiyou/freeposte.io/master/freeposte.env
```
These templates are used for development environment. So, if you do not plan
on biulding Freeposte from source, simply remove the ``build:`` references:
```
sed -i '/build:/d' docker-compose.yml
```
Finally, edit the ``freeposte.env`` file and update the following settings:
- set ``DEBUG`` to ``False`` unless your are debugging,
- set ``SECRET_KEY`` to a random 16 bytes string,
- set ``DOMAIN`` to your main mail domain,
- set ``ADMIN`` to the local part of the admin address on the main domain,
- set ``HOSTNAME`` to your mailserver hostname.
Setting up certificates
=======================
Freeposte relies heavily on TLS and must have a key pair and a certificate
available, at least for the hostname configured in ``freeposte.env``.
Create the certificate directory:
```
mkdir /freeposte/certs
```
Then create two files in this directory:
- ``cert.pem`` contains the certificate,
- ``key.pem`` contains the key pair.
Bootstrapping the database
==========================
Freeposte does not yet have a database initialization or migration system.
This will be added in version ``1.1``. For now, you will have to manually
bootstrap the database. First, start the mail server stack:
```
docker-compose up -d
```
Then bootstrap the database:
```
docker exec -i -t freeposte_amin_1 python initdb.py
docker-compose restart
```
Be very careful and run this command only once, as it will remove any existing
data before creating a fresh database.
The default user is ``admin@example.com`` with password ``admin``. Connect to
the Web admin interface and setup a proper domain with your own admin user
before removing the default one:
```
https://your-host-name.tld/admin/
```
Testing before going live
=========================
You should test all the critical features before using the mail server for
actual messages. Try to send and receive e-mails, monitor the logs for some
unexpected errors, etc.
Your server should now be running!

23
MANAGE.md Normal file
View File

@@ -0,0 +1,23 @@
Upgrading the mail server
=========================
First check upstream for changes in the ``docker-compose.yml`` or in the
``freeposte.env`` files. Update these files, then simply pull the latest
images and recreate the containers :
```
docker-compose pull
docker-compose up -d
```
Monitoring the mail server
==========================
Logs are managed by Docker directly. You can easily read your logs using :
```
docker-compose logs
```
Docker is able to forward logs to multiple log engines. Read the following documentation or details: https://docs.docker.com/engine/admin/logging/overview/.

80
README.md
View File

@@ -32,71 +32,17 @@ The mail infrastructure is based on a standard MTA-LDA pattern :
Running a mail server Running a mail server
===================== =====================
The mail server runs as a set of Docker containers. These containers are managed Freeposte runs on top of Docker for easy packaging and upgrades. All you need
through a ``docker-compose.yml`` configuration file that requires Docker Compose is a proper system with Docker and Compose installed, then simply download
to run. the ``docker-compose.yml`` and sample ``freeposte.env``, tune them to your
needs and fire up the mail server:
First, follow instructions at https://docs.docker.com to setup Docker and Docker
Compose properly for your system. Then download the main configuration files:
```
wget https://raw.githubusercontent.com/kaiyou/freeposte.io/master/docker-compose.yml
wget https://raw.githubusercontent.com/kaiyou/freeposte.io/master/freeposte.env
```
The ``docker-compose.yml`` file contains instructions about which containers to run and how they will
interact. ``freeposte.env`` is the main configuration file. You must read it and provide proper configuration before running the server.
You will also need to create a data directory. Freeposte will use ``/data``
as a sane default:
```
mkdir -p /data
```
Otherwise, simply edit the ``docker-compose.yml`` to match your requirements. Finally, you can run your mail server:
``` ```
docker-compose up -d docker-compose up -d
``` ```
Upgrading the mail server For a detailed walktrough, see ``INSTALL.md``. Also, see ``MANAGE.md`` for
========================= details about daily maintenance of your mail server.
First check upstream for changes in the ``docker-compose.yml`` or in the
``freeposte.env`` files. Update these files, then simply pull the latest
images and recreate the containers :
```
docker-compose pull
docker-compose up -d
```
Monitoring the mail server
==========================
Logs are managed by Docker directly. You can easily read your logs using :
```
docker-compose logs
```
Docker is able to forward logs to multiple log engines. Read the following documentation or details: https://docs.docker.com/engine/admin/logging/overview/.
Building from source
====================
You can simply build all the containers from source using the ``docker-compose.yml``. First clone the Git repository:
```
git clone https://github.com/kaiyou/freeposte.io.git
```
Then build all the images:
```
docker-compose build
```
Development environment Development environment
======================= =======================
@@ -121,3 +67,17 @@ And finally run the server with debug enabled:
``` ```
python run.py python run.py
``` ```
Philosophy
==========
The mailserver is designed as a whole, some images are therefore not best
suited for reuse outside this project. All images should however follow
Docker best practices and be as generic as possible :
- even if not suited for reuse, they should be simple enough to
fit as base images for other projects,
- interesting settings should be available as environment variables
- base images should be well-trusted (officiel Alpine or Debian for instance).