Skip to content
Oasis automates the setup of a Raspberry Pi email server meant to run from inside your home
Python Shell Nginx
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Oasis automates the setup of a Raspberry Pi email server meant to run from inside your home. In the home environment, ISPs and user equipment can make it difficult to externally reach home-based email servers due to port blocking. Also, in most cases it's expensive to obtain a static IP address which is necessary to successfully run a mail server.

To work around these issues Oasis provisions a cloud-based component that acts as a gateway to your home-based Raspberry Pi server. This cloud component is stateless and all data received is immediately forwarded to your pi for safe storage.



  1. Raspberry Pi 3 + microUSB Cable + Ethernet cable
  2. MicroSD card, 32GB Class 10 minimum recommended, with SD card reader/adapter

Windows Users

We recommend that you install putty so you have a good ssh client to access your Pi. Putty is available here: (choose putty.exe, or the MSI installer). Launch putty.exe to have an open terminal for all the commands specified below.

Linux Users

We have tested Ubuntu 14.04 and 16.04. Please install avahi-daemon for discovering the Pi on the network - $ sudo apt-get install avahi-daemon

Preparing the Pi

  1. Download the latest Oasis Raspbian Image ( [the project used to generate the image is here]
  2. Flash your microSD card with the unzipped Oasis Image (
  3. Insert the microSD card into the microSD card socket on the bottom of the Pi
  4. Connect your Pi to your router using an Ethernet Cable
  5. Connect your Pi to your laptop using a microUSB cable or to a power plug
  6. Log into your Pi - $ ssh pi@raspberrypi.local - the default password is 'raspberry'
  7. Change your password to a secure password - $ passwd
    • We recommend using a password manager for generating and storing strong passwords
  8. Configure wifi on your Pi (

Preparing your cloud configuration

  1. Create an account with AWS - sign up for 1 year of free tier services (
    • Verify your account:
    • Check your email for any additional verification steps and complete them as needed
    • If you want to use the free tier service, you will need to edit group_vars/all/vars.yml and set instance_size to 't2.micro'. After your free service is over, this instance size will cost ~$10/month. You can automatically switch to a smaller instance that costs ~$5/month by changing the value back to 't2.nano' and re-running the playbook.
    • If you already have an AWS account and have exhausted your free services, the services required to support Oasis are a t2.nano instance and a hosted zone. We estimate charges to be ~$5-6/month for a t2.nano with DNS services.
  2. Register a domain that will be used for email (e.g.:
    • We suggest using Amazon Web Services (AWS) to skip manually configuring DNS. You will receive an email asking to verify your registration - click the link in the email.
    • If you are using a domain registered with another service it is likely not using AWS for DNS and you will need to configure your domain to use AWS DNS services (
  3. In the AWS web console, go to Identity Access and Management (IAM) and create a user account and save the credentials for the account (AWS_ACCESS_KEY and AWS_SECRET_ACCESS_KEY). ( You will need to assign the following permissions to the user under Managed Policies (
    • AmazonEC2FullAccess
    • AmazonRoute53FullAccess
  4. Submit a request to Amazon to get reverse DNS support after you have completed the Quickstart section below. This will help ensure mail deliverability. Your elastic IP address will be available in group_vars/all/vars.yml after you have completed the Quickstart. The reverse DNS record is where you replace with your custom domain. For the Use Case Description section the form, you can enter "personal email gateway". (


  1. Log into your Pi - $ ssh pi@raspberrypi.local
  2. Clone this repository - $ git clone --recursive
  3. $ cd oasis
  4. Run the oasis script - $ ./ --both
  5. When prompted, carefully enter responses for the following values
    • Domain - (e.g.:
    • First Name (e.g.: Louis)
    • Last Name (e.g.: Brandeis)
    • Username - (e.g. louis, creates the email address
    • Password - We recommend using a password manager for generating and storing strong passwords
    • Confirm Password
    • AWS Access Key
    • AWS Secret Access Key
  6. You will be prompted to specify a vault password. The vault password is used to encrypt the information you provided in the prompts above, along with some randomly generated passwords.
    • We recommend using a password manager for generating and storing strong passwords
  7. After the vault password prompt, you will soon be prompted to accept the SSH key for the gateway. Type 'yes' and press 'Enter'. If execution fails after this point, you will need to edit your .ssh/known_hosts file and remove this host before running the playbooks again.
  8. Configure your mail (IMAP), calendar (CalDAV) and contacts (CardDAV) clients as follows from values you input when prompted during the install:
    • username: louis
    • password: strong_password_here
    • server name:
    • IMAP port: 993
    • SMTP port: 587
    • CalDAV and CardDAV port: 8443


For testing and development purposes a Vagrant configuration is supplied that allows you to run the components that would normally execute in your Raspberry Pi, inside a virtual machine. The cloud based gateway component still executes in AWS of Digital Ocean.

To run in development mode:

  1. Install the latest version of Vagrant on your development machine
  2. Navigate to this source directory from the command line
  3. $ vagrant up
  4. $ vagrant ssh
  5. $ cd /vagrant_data
  6. $ ansible-playbook -i inventory image.yml --tags "packages"
  7. $ ./ --both
You can’t perform that action at this time.