Add a proper INSTALL documentation
Pierre Jaury
8 years ago
parent
45200b886b
commit
37cae069ea
@ -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!
|
||||
@ -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/.
|
||||
Loading…
Reference in New Issue