Add a proper INSTALL documentation
Pierre Jaury
9 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