Go to file
Adrià Casajús 73a0addf27
Remove bad word from wordlist
2023-10-03 12:04:50 +02:00
.github Update dependencies (#1901) 2023-09-29 17:26:40 +02:00
app Add index on created_at for EmailLog (#1898) 2023-09-28 18:26:40 +02:00
docs Documented CAA (#1804) 2023-07-24 21:51:17 +02:00
local_data Remove bad word from wordlist 2023-10-03 12:04:50 +02:00
migrations Add index on created_at for EmailLog (#1898) 2023-09-28 18:26:40 +02:00
monitor chore: add upcloud monitoring (#1835) 2023-08-04 12:19:00 +02:00
scripts Update docs to the same port as the reset script + remove pre-commit pylint (#1464) 2022-12-02 17:31:31 +01:00
static Update package-lock.json to fix build error (#1732) 2023-05-10 11:18:45 +02:00
templates Update dns.html to amend DKIM configuration instructions (#1884) 2023-09-26 12:21:23 +02:00
tests Allow to get premium partner domains without premium sl domains (#1880) 2023-09-13 18:12:47 +02:00
.dockerignore Obtain git information from version file 2022-05-12 16:11:20 +02:00
.flake8 add B001 to flake8 2022-04-22 10:39:01 +02:00
.gitattributes add .gitattributes file to override linguist 2020-05-11 09:49:44 +02:00
.gitignore Tranfer aliases to a new mailbox when deleting mailboxes (#1534) 2023-01-17 11:55:34 +01:00
.jshintrc create .jshintrc file, set esversion=8 2021-11-03 10:20:21 +01:00
.pre-commit-config.yaml Reformat base64 encoded messages to shorter lines (#1575) 2023-02-21 15:28:06 +01:00
.pylintrc Update pre-commit (#1138) 2022-07-04 16:01:04 +02:00
.version Obtain git information from version file 2022-05-12 16:11:20 +02:00
CHANGELOG Update pre-commit (#1138) 2022-07-04 16:01:04 +02:00
CONTRIBUTING.md mention about proton mail during signup (#1796) 2023-07-10 14:41:52 +02:00
Dockerfile Update dockerfile to use netcat-traditional (#1782) 2023-06-22 10:58:00 +02:00
LICENSE Use AGPL license instead of MIT 2021-08-21 19:03:48 +02:00
README.md Specify how to create the certificates if they don't exist in readme (#1533) 2023-01-17 20:09:41 +01:00
SECURITY.md Update pre-commit (#1138) 2022-07-04 16:01:04 +02:00
alembic.ini Use alembic instead of flask migrate which depends on flask-sqlalchemy 2021-10-14 15:45:17 +02:00
coverage.ini Use install-poetry to use poetry with caching. 2022-02-06 16:08:40 +00:00
cron.py Delete old email_log entries in batches to avoid table lock (#1902) 2023-10-02 10:50:02 +02:00
crontab-all-hosts.yml Fix: Create crontab for all hosts (#1396) 2022-11-02 18:13:24 +01:00
crontab.yml Schedule deletion of users (#1872) 2023-09-10 22:11:50 +02:00
email_handler.py allow BCC (#1894) 2023-09-26 10:00:33 +02:00
example.env DB port correction (#1214) 2022-08-03 16:04:03 +02:00
init_app.py Alias domain as contact domain (#1689) 2023-04-20 12:14:53 +02:00
job_runner.py Fix format (#1554) 2023-01-25 13:16:29 +01:00
monitoring.py chore: add upcloud monitoring (#1835) 2023-08-04 12:19:00 +02:00
newrelic.ini remove Metric 2021-07-28 18:20:18 +02:00
oauth_tester.py change docs.simplelogin.to to https://simplelogin.io/docs/siwsl/app/ (#1640) 2023-03-17 15:39:47 +01:00
poetry.lock Update dependencies (#1901) 2023-09-29 17:26:40 +02:00
pyproject.toml Update dependencies (#1901) 2023-09-29 17:26:40 +02:00
pytest.ci.ini Moved pytest.ini to pytest.ci.ini 2022-05-20 14:45:33 +02:00
server.py Fix: only send subscription notification if there is a valid subscription (#1762) 2023-05-31 18:20:18 +02:00
shell.py Display recovery codes for mfa only once (#1317) 2022-10-03 12:32:45 +02:00
wsgi.py create BaseForm to enable CSRF 2019-07-02 10:20:12 +03:00


SimpleLogin | Protect your online identity with email alias

Your email address is your online identity. When you use the same email address everywhere, you can be easily tracked. More information on https://simplelogin.io

This README contains instructions on how to self host SimpleLogin.

Once you have your own SimpleLogin instance running, you can change the API URL in SimpleLogin's Chrome/Firefox extension, Android/iOS app to your server.

SimpleLogin roadmap is at https://github.com/simple-login/app/projects/1 and our forum at https://github.com/simple-login/app/discussions, feel free to submit new ideas or vote on features.


  • a Linux server (either a VM or dedicated server). This doc shows the setup for Ubuntu 18.04 LTS but the steps could be adapted for other popular Linux distributions. As most of components run as Docker container and Docker can be a bit heavy, having at least 2 GB of RAM is recommended. The server needs to have the port 25 (email), 80, 443 (for the webapp), 22 (so you can ssh into it) open.

  • a domain that you can config the DNS. It could be a sub-domain. In the rest of the doc, let's say it's mydomain.com for the email and app.mydomain.com for SimpleLogin webapp. Please make sure to replace these values by your domain name whenever they appear in the doc. A trick we use is to download this README file on your computer and replace all mydomain.com occurrences by your domain.

Except for the DNS setup that is usually done on your domain registrar interface, all the below steps are to be done on your server. The commands are to run with bash (or any bash-compatible shell like zsh) being the shell. If you use other shells like fish, please make sure to adapt the commands.

Some utility packages

These packages are used to verify the setup. Install them by:

sudo apt update && sudo apt install -y dnsutils

Create a directory to store SimpleLogin data:

mkdir sl
mkdir sl/pgp # to store PGP key
mkdir sl/db # to store database
mkdir sl/upload # to store quarantine emails


From Wikipedia https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail

DomainKeys Identified Mail (DKIM) is an email authentication method designed to detect forged sender addresses in emails (email spoofing), a technique often used in phishing and email spam.

Setting up DKIM is highly recommended to reduce the chance your emails ending up in the recipient's Spam folder.

First you need to generate a private and public key for DKIM:

openssl genrsa -out dkim.key 1024
openssl rsa -in dkim.key -pubout -out dkim.pub.key

You will need the files dkim.key and dkim.pub.key for the next steps.

For email gurus, we have chosen 1024 key length instead of 2048 for DNS simplicity as some registrars don't play well with long TXT record.


Please note that DNS changes could take up to 24 hours to propagate. In practice, it's a lot faster though (~1 minute or so in our test). In DNS setup, we usually use domain with a trailing dot (.) at the end to to force using absolute domain.

MX record

Create a MX record that points mydomain.com. to app.mydomain.com. with priority 10.

To verify if the DNS works, the following command

dig @ mydomain.com mx

should return:

mydomain.com.	3600	IN	MX	10 app.mydomain.com.

A record

An A record that points app.mydomain.com. to your server IP. If you are using CloudFlare, we recommend to disable the "Proxy" option. To verify, the following command

dig @ app.mydomain.com a

should return your server IP.


Set up DKIM by adding a TXT record for dkim._domainkey.mydomain.com. with the following value:

v=DKIM1; k=rsa; p=PUBLIC_KEY

with PUBLIC_KEY being your dkim.pub.key but

  • remove the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----
  • join all the lines on a single line.

For example, if your dkim.pub.key is

-----END PUBLIC KEY-----

then the PUBLIC_KEY would be abcdefgh.

You can get the PUBLIC_KEY by running this command:

sed "s/-----BEGIN PUBLIC KEY-----/v=DKIM1; k=rsa; p=/g" $(pwd)/dkim.pub.key | sed 's/-----END PUBLIC KEY-----//g' |tr -d '\n' | awk 1

To verify, the following command

dig @ dkim._domainkey.mydomain.com txt

should return the above value.


From Wikipedia https://en.wikipedia.org/wiki/Sender_Policy_Framework

Sender Policy Framework (SPF) is an email authentication method designed to detect forging sender addresses during the delivery of the email

Similar to DKIM, setting up SPF is highly recommended. Add a TXT record for mydomain.com. with the value:

v=spf1 mx ~all

What it means is only your server can send email with @mydomain.com domain. To verify, the following command

dig @ mydomain.com txt

should return the above value.


From Wikipedia https://en.wikipedia.org/wiki/DMARC

It (DMARC) is designed to give email domain owners the ability to protect their domain from unauthorized use, commonly known as email spoofing

Setting up DMARC is also recommended. Add a TXT record for _dmarc.mydomain.com. with the following value

v=DMARC1; p=quarantine; adkim=r; aspf=r

This is a relaxed DMARC policy. You can also use a more strict policy with v=DMARC1; p=reject; adkim=s; aspf=s value.

To verify, the following command

dig @ _dmarc.mydomain.com txt

should return the set value.

For more information on DMARC, please consult https://tools.ietf.org/html/rfc7489


Now the boring DNS stuffs are done, let's do something more fun!

If you don't already have Docker installed on your server, please follow the steps on Docker CE for Ubuntu to install Docker.

You can also install Docker using the docker-install script which is

curl -fsSL https://get.docker.com | sh

Prepare the Docker network

This Docker network will be used by the other Docker containers run in the next steps. Later, we will setup Postfix to authorize this network.

sudo docker network create -d bridge \
    --subnet= \
    --gateway= \


This section creates a Postgres database using Docker.

If you already have a Postgres database in use, you can skip this section and just copy the database configuration (i.e. host, port, username, password, database name) to use in the next sections.

Run a Postgres Docker container as your Postgres database server. Make sure to replace myuser and mypassword with something more secret.

docker run -d \
    --name sl-db \
    -e POSTGRES_PASSWORD=mypassword \
    -e POSTGRES_USER=myuser \
    -e POSTGRES_DB=simplelogin \
    -p \
    -v $(pwd)/sl/db:/var/lib/postgresql/data \
    --restart always \
    --network="sl-network" \

To test whether the database operates correctly or not, run the following command:

docker exec -it sl-db psql -U myuser simplelogin

you should be logged in the postgres console. Type exit to exit postgres console.


Install postfix and postfix-pgsql. The latter is used to connect Postfix and the Postgres database in the next steps.

sudo apt-get install -y postfix postfix-pgsql -y

Choose "Internet Site" in Postfix installation window then keep using the proposed value as System mail name in the next window.

Replace /etc/postfix/main.cf with the following content. Make sure to replace mydomain.com by your domain.

# POSTFIX config file, adapted for SimpleLogin
smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no

# appending .domain is the MUA's job.
append_dot_mydomain = no

# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h

readme_directory = no

# See http://www.postfix.org/COMPATIBILITY_README.html -- default to 2 on
# fresh installs.
compatibility_level = 2

# TLS parameters
smtpd_tls_session_cache_database = btree:${data_directory}/smtpd_scache
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache
smtp_tls_security_level = may
smtpd_tls_security_level = may

# See /usr/share/doc/postfix/TLS_README.gz in the postfix-doc package for
# information on enabling SSL in the smtp client.

alias_maps = hash:/etc/aliases
mynetworks = [::ffff:]/104 [::1]/128

# Set your domain here
mydestination =
myhostname = app.mydomain.com
mydomain = mydomain.com
myorigin = mydomain.com

relay_domains = pgsql:/etc/postfix/pgsql-relay-domains.cf
transport_maps = pgsql:/etc/postfix/pgsql-transport-maps.cf

# HELO restrictions
smtpd_delay_reject = yes
smtpd_helo_required = yes
smtpd_helo_restrictions =

# Sender restrictions:
smtpd_sender_restrictions =

# Recipient restrictions:
smtpd_recipient_restrictions =
   reject_rbl_client zen.spamhaus.org,
   reject_rbl_client bl.spamcop.net,

Check that the ssl certificates /etc/ssl/certs/ssl-cert-snakeoil.pem and /etc/ssl/private/ssl-cert-snakeoil.key exist. Depending on the linux distribution you are using they may or may not be present. If they are not, you will need to generate them with this command:

openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout /etc/ssl/private/ssl-cert-snakeoil.key -out /etc/ssl/certs/ssl-cert-snakeoil.pem

Create the /etc/postfix/pgsql-relay-domains.cf file with the following content. Make sure that the database config is correctly set, replace mydomain.com with your domain, update 'myuser' and 'mypassword' with your postgres credentials.

# postgres config
hosts = localhost
user = myuser
password = mypassword
dbname = simplelogin

query = SELECT domain FROM custom_domain WHERE domain='%s' AND verified=true
    UNION SELECT '%s' WHERE '%s' = 'mydomain.com' LIMIT 1;

Create the /etc/postfix/pgsql-transport-maps.cf file with the following content. Again, make sure that the database config is correctly set, replace mydomain.com with your domain, update 'myuser' and 'mypassword' with your postgres credentials.

# postgres config
hosts = localhost
user = myuser
password = mypassword
dbname = simplelogin

# forward to smtp: for custom domain AND email domain
query = SELECT 'smtp:' FROM custom_domain WHERE domain = '%s' AND verified=true
    UNION SELECT 'smtp:' WHERE '%s' = 'mydomain.com' LIMIT 1;

Finally, restart Postfix

sudo systemctl restart postfix

Run SimpleLogin Docker containers

To run SimpleLogin, you need a config file at $(pwd)/simplelogin.env. Below is an example that you can use right away, make sure to

  • replace mydomain.com by your domain,
  • set FLASK_SECRET to a secret string,
  • update 'myuser' and 'mypassword' with your database credentials used in previous step.

All possible parameters can be found in config example. Some are optional and are commented out by default. Some have "dummy" values, fill them up if you want to enable these features (Paddle, AWS, etc).

# WebApp URL

# domain used to create alias

# transactional email is sent from this email address

# custom domain needs to point to these MX servers
EMAIL_SERVERS_WITH_PRIORITY=[(10, "app.mydomain.com.")]

# By default, new aliases must end with ".{random_word}". This is to avoid a person taking all "nice" aliases.
# this option doesn't make sense in self-hosted. Set this variable to disable this option.

# the DKIM private key used to compute DKIM-Signature

# DB Connection





Before running the webapp, you need to prepare the database by running the migration:

docker run --rm \
    --name sl-migration \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    -v $(pwd)/simplelogin.env:/code/.env \
    --network="sl-network" \
    simplelogin/app:3.4.0 flask db upgrade

This command could take a while to download the simplelogin/app docker image.

Init data

docker run --rm \
    --name sl-init \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    --network="sl-network" \
    simplelogin/app:3.4.0 python init_app.py

Now, it's time to run the webapp container!

docker run -d \
    --name sl-app \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    -p \
    --restart always \
    --network="sl-network" \

Next run the email handler

docker run -d \
    --name sl-email \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    -p \
    --restart always \
    --network="sl-network" \
    simplelogin/app:3.4.0 python email_handler.py

And finally the job runner

docker run -d \
    --name sl-job-runner \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    --restart always \
    --network="sl-network" \
    simplelogin/app:3.4.0 python job_runner.py


Install Nginx and make sure to replace mydomain.com by your domain

sudo apt-get install -y nginx

Then, create /etc/nginx/sites-enabled/simplelogin with the following lines:

server {
    server_name  app.mydomain.com;

    location / {
        proxy_pass http://localhost:7777;

Reload Nginx with the command below

sudo systemctl reload nginx

At this step, you should also setup the SSL for Nginx. Here's our guide how.


If all the above steps are successful, open http://app.mydomain.com/ and create your first account!

By default, new accounts are not premium so don't have unlimited alias. To make your account premium, please go to the database, table "users" and set "lifetime" column to "1" or "TRUE":

docker exec -it sl-db psql -U myuser simplelogin
UPDATE users SET lifetime = TRUE;

Once you've created all your desired login accounts, add these lines to /simplelogin.env to disable further registrations:


Then restart the web app to apply: docker restart sl-app

Donations Welcome

You don't have to pay anything to SimpleLogin to use all its features. If you like the project, you can make a donation on our Open Collective page at https://opencollective.com/simplelogin


The above self-hosting instructions correspond to a freshly Ubuntu server and doesn't cover all possible server configuration. Below are pointers to different topics:

❤️ Contributors

Thanks go to these wonderful people:

Dung Nguyen Van
Dung Nguyen Van

Giuseppe Federico
Giuseppe Federico

Ninh Dinh
Ninh Dinh

Tung Nguyen V. N.
Tung Nguyen V. N.

Son Nguyen Kim
Son Nguyen Kim

Raymond Nook
Raymond Nook

Sibren Vasse
Sibren Vasse

Sylvia van Os
Sylvia van Os