This repository is a collection of ansible roles designed to help deploy a self-hosted version of SimpleLogin, an open-source email aliasing service. This script automates the steps as outlined by SimpleLogin. This deployment optionally supports automatic backups of the postgres database to backblaze and optionally automatically sets any user that is created to lifetime premium. It uses docker compose to run the simplelogin python applications. Nginx and postfix will run without docker on the system.
The official SimpleLogin documentation, while comprehensive, was difficult to navigate and contained outdated sections at the time we attempted to use it. For example, which database migration, with what commands, in what order, had to be run, etcetera. As a result, we created this repository to streamline and partly automate the process of setting up SimpleLogin with Ansible.
The goal of these roles is to:
- Automate the deployment of a self-hosted SimpleLogin instance.
- Simplify the configuration and installation process.
- Create a reproduceable deployment of simplelogin on selfhosted hardware.
- Provide a reusable and customizable solution for those looking to host their own email aliasing service, built by SimpleLogin.
We have been experimenting with deploying this ourselves for email privacy apps we are building at Codemoon. Ultimately we ran into uncertainties regarding email deliverability and opted to use another email provider to handle this. However, for those self-hosting, SimpleLogin should work well enough and this ansible playbook can assist in deploying it efficiently and repeatably.
- Automated installation and configuration of dependencies and firewall of the VM.
- Configures nginx with a tls certificate with let's encrypt. You can disable this easily by commenting out the role in deploy-sl.yml if you use your own reverse proxy.
- Runs database migrations, sets up database, and SimpleLogin backend/frontend components.
- Sets up simplelogin stack, you end up with a docker compose setup.
- Automatically set your newly registered users to lifetime premium.
- Create backups of the database to backblaze
| Role | Description |
|---|---|
| dkim | This creates dkim files (for spf and dmarc records) on your target VM. On subsequent runs, it won't overwrite existing dkim records. |
| packages | This role installs packages dnsutils that you can use for debugging dns records |
| firewall | This role installs ufw and configures the firewall of your VM |
| dirs | This role creates the directories sl, sl/db, sl/pgp and sl/upload with the correct permissions. |
| geerlingguy.docker | This role installs docker, creates the docker network and adds your user to the docker group. |
| dockerconfig | This role configures the docker network. |
| postgresdocker | This role installs postgres with a docker container and runs the necessary migrations for simplelogin. Optionally it also creates a backup cronjob and uploads the result to backblaze if enabled. Optionally a postgres trigger is added that automatically sets new users to premium. |
| postfix | This role automatically installs postfix with the correct installation steps, installs the package postfix-pgsql and creates the required configuration files for postfix. |
| sl | This role creates the docker compose file and creates all docker containers of the simplelogin stack. |
| nginx | This role creates an nginx reverse proxy in front of your simplelogin app and automatically configures a TLS certificate signed by let's encrypt. In case you would like to use your own reverse proxy like traefik or caddy you can modify this step. Make sure you keep updating the postfix main.cf file to use the new certificates. |
| finalize | This role echoes a message to your console with the link to your simplelogin instance. |
- Basic understanding of ansible, linux, ssh
- A (sub)domain where you can manage the DNS records.
- An Ubuntu 22.04+ or Debian 12 VM with 1 vCPU, 10G disk and 2G of RAM minimum. This VM should have a publicly reachable IPv4 address and outbound traffic should be allowed on port 25.
- SSH access to the VM with ssh key
- Linux user added to sudoers group
- Ansible-core >= 2.17.4 on your controller machine (tested with ansible-core 2.17.4)
- Ansible collections installed:
ansible-galaxy role install geerlingguy.dockeransible-galaxy collection install community.generalansible-galaxy collection install community.dockeransible-galaxy collection install community.postgresql
- Optional: backblaze bucket for postgres database backups (recommended)
-
Acquire prerequisites
-
Clone this repository:
git clone https://github.com/codemoon-io/simplelogin-ansible.git cd simplelogin-ansible -
Customize the
vars/main.ymlfile to your values. -
Customize the
inventory.ymlfile to match your target VM. -
Set an A record of the prefix.domain to your VM's IPv4 address.
-
Run the Ansible playbook:
ansible-playbook deploy-sl.yml -i inventory.yml
-
Setup the MX, SPF and DMARC records as specified in simplelogin's documentation, using the DKIM files that were created on the VM when you ran the ansible playbook.
-
Go to https://prefix.domain to register an account on your self hosted instance and enjoy your self-hosted email forwarding aliases 🎉!
-
While we were able to deploy SimpleLogin using these roles, we eventually switched to another mail provider for better deliverability. We decided this because we didn't want to actively have to manage deliverability of emails, but for a self-hosted instance, SimpleLogin should work well enough.
-
If you find that one of the roles fail during deployment on your system, you can comment some roles so that they won't run again during subsequent tries.
-
These roles are provided "as-is" and may require adjustments based on the specific server environment or changes in SimpleLogin's requirements. We don't provide support on the deployments but feel free to create a pull request if there are bugs.
-
If you wish to make further adjustments to the deployment you could do so via the simplelogin.env file that is created on the VM on /home/{{ linuxuser }}/simplelogin.env. See simplelogin's documentation about how to configure the environment file for further customization options.
-
We recommend UpCloud to get a VM, as this is what simplelogin says they use too (clean IP ranges, cost-effective hardware). In case you would like to support yourself (and us too), here is an affiliate link so you get 25€ hosting credits for free which will also give us some free hosting credits. Affiliate link. You will still have to ask them to open port 25 for you.
If you'd like to improve this repository, feel free to submit a pull request or open an issue. Any contributions that can further streamline or improve the deployment process are welcome! For example, we see some areas for improvement, like putting the vars files in each role instead of globally. We thought it was easier this way but it may be less configurable like this.
This repository is licensed under the MIT License. See the LICENSE file for more details.
Thanks goes out to SimpleLogin and Jeff Geerling for their contributions to open source.