Move some documentation to the Github Wiki
Pierre Jaury
8 years ago
parent
52070937f9
commit
c19ba6d69a
@ -1,216 +0,0 @@
|
||||
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.io 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.io 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.io.
|
||||
|
||||
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 multiple containers systems
|
||||
like Freeposte.io.
|
||||
|
||||
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.io 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.io 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 building Freeposte.io from source, simply remove the ``build:`` references:
|
||||
|
||||
```
|
||||
sed -i '/build:/d' docker-compose.yml
|
||||
```
|
||||
|
||||
The default configuration will pull the latest image built from the Docker
|
||||
Hub, which is based on the latest commit on GitHub. This behaviour is ok for
|
||||
evaluating Freeposte.io, but you should at least specify a branch. You will
|
||||
still get bugfixes and security updates, but breaking changed will not be
|
||||
pulled unless you explicitely change the branch number. To specify you want
|
||||
to pull the ``1.0`` branch, simply add the version number to the ``image``
|
||||
field:
|
||||
|
||||
```
|
||||
VERSION=1.0
|
||||
sed -i "/image:/s/\(:[0-9.]*\)\?$/:$VERSION/" docker-compose.yml
|
||||
```
|
||||
|
||||
You should always have all containers using the same branch.
|
||||
|
||||
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.io 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.
|
||||
|
||||
Creating the first admin user
|
||||
=============================
|
||||
|
||||
Freeposte.io does not come with any default user. You have to create the
|
||||
first admin user manually. First, start the mail server stack:
|
||||
|
||||
```
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
Then create the admin user:
|
||||
|
||||
```
|
||||
docker exec -i -t freeposte_admin_1 python manage.py admin admin exmaple.net admin
|
||||
```
|
||||
|
||||
This will create ``admin@example.net`` with password ``admin``. Connect to
|
||||
the Web admin interface change the password to a strong 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!
|
||||
@ -1,23 +0,0 @@
|
||||
|
||||
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/.
|
||||
Loading…
Reference in New Issue