diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..e1eed6b4 --- /dev/null +++ b/INSTALL.md @@ -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! \ No newline at end of file diff --git a/MANAGE.md b/MANAGE.md new file mode 100644 index 00000000..6af914ab --- /dev/null +++ b/MANAGE.md @@ -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/. \ No newline at end of file diff --git a/README.md b/README.md index 5ecf5084..e578bb06 100644 --- a/README.md +++ b/README.md @@ -32,71 +32,17 @@ The mail infrastructure is based on a standard MTA-LDA pattern : Running a mail server ===================== -The mail server runs as a set of Docker containers. These containers are managed -through a ``docker-compose.yml`` configuration file that requires Docker Compose -to run. - -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: +Freeposte runs on top of Docker for easy packaging and upgrades. All you need +is a proper system with Docker and Compose installed, then simply download +the ``docker-compose.yml`` and sample ``freeposte.env``, tune them to your +needs and fire up the mail server: ``` docker-compose up -d ``` -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/. - -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 -``` +For a detailed walktrough, see ``INSTALL.md``. Also, see ``MANAGE.md`` for +details about daily maintenance of your mail server. Development environment ======================= @@ -121,3 +67,17 @@ And finally run the server with debug enabled: ``` 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). + +