Postal installation is not very straightforward. The process is fairly complex. It’s because Postal needs several packages to be installed beforehand, it can be used. I have tried to make it as simple as possible.
Requirement for Postal SMTP server
- A domain name from Namecheap or Namesilo
- A VPS or cloud with a minimum of 4 GB RAM and 2 vCPU
- Operating System: Ubuntu 20.04 or Ubuntu 18.04 or CentOS 7
I am using Contabo for the purpose of demonstration.
In order to start with installation, you will need to connect to the server. If you are on you have to get an SSH client for this purpose. One such SSH client is Putty. But if you are on Linux or Mac, just open the terminal and type email@example.com where xx.x.x.xxx is your server IP address.
First of all switch to root user
After that update and upgrade your Ubuntu
apt update -y apt upgrade -y
Next setup hostname. Replace “inlearn.in” with your domain name.
hostnamectl set-hostname mail.inlearn.in
Updating DNS records
Login to the domain registrar and create A record for mail.yourdomain.com
Now let’s begin with the installation.
Note: This is a new installation guide. If you are looking for an old installation guide scroll down.
Installing Docker and Docker-Compose
Recently postal team switched to docker mode to make installation easier for the end-users. Therefore we need to install Docker and Docker-Compose first. I already have discussed what is docker, docker-compose & installation steps in detail. Feel free to read the article to have a clear understanding of docker.
First of all, set a few packages to set up the Docker repository
sudo apt-get install apt-transport-https ca-certificates curl software-properties-common -y
Next, add Docker’s official GPG key.
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
Now, you can install the Docker repository using the following commands
echo \ "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Next update the system software
sudo apt-get update -y
Finally, run the following command to install Docker Engine and containerd.
sudo apt-get install docker-ce docker-ce-cli containerd.io
First of all download the current stable release of Docker Compose:
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
Next, update the permission to binary
sudo chmod +x /usr/local/bin/docker-compose
Finally, test the docker-compose installation
You will see the docker-compose version. If you see anything else this means something has gone wrong.
Installing Additional Prerequisites for Postal SMTP
After installation of Docker and Docker-compose, you need to install a few other packages like Git, MariaDB, RabbitMQ, etc.
So, let’s install them one by one.
First, install git and git curl
apt install git -y apt install git curl jq
Next clone the postal helper repository
git clone https://postalserver.io/start/install /opt/postal/install sudo ln -s /opt/postal/install/bin/postal /usr/bin/postal
Now, you can install MariaDB in the docker container
docker run -d \ --name postal-mariadb \ -p 127.0.0.1:3306:3306 \ --restart always \ -e MARIADB_DATABASE=postal \ -e MARIADB_ROOT_PASSWORD=postalpassword \ mariadb
RabbitMQ is necessary to process messages and distribute the loads
To install it, run the following commands
docker run -d \ --name postal-rabbitmq \ -p 127.0.0.1:5672:5672 \ --restart always \ -e RABBITMQ_DEFAULT_USER=postal \ -e RABBITMQ_DEFAULT_PASS=password \ -e RABBITMQ_DEFAULT_VHOST=postalvhost \ rabbitmq:3.8
Now we have installed all the prerequisite packages, it’s time to install Postal
The postal repository, you installed earlier, is capable of generating some configuration files to use
Run the following command.
postal bootstrap mail.inlearn.in
The above command generates 3 files. Out of which postal.yml is of our interest.
You need to edit the postal.yml and make changes. But before that install an editor. I suggest installing nano.
apt install nano -y
Now to edit postal.yml run the following command
You will see output something like this
# The host that the management interface will be available on host: mail.inlearn.in # The protocol that requests to the management interface should happen on protocol: https web_server: # Specify configuration for the Postal web server bind_address: 126.96.36.199 port: 5000 smtp_server: # Specify configuration to the Postal SMTP server port: 25 logging: # Specify options for the logging stdout: true main_db: # Specify the connection details for your MySQL database host: 127.0.0.1 username: root password: postalpassword database: postal message_db: # Specify the connection details for your MySQL server that will be house the # message databases for mail servers. host: 127.0.0.1 username: root password: postalpassword prefix: postal rabbitmq: # Specify connection details for your RabbitMQ server host: 127.0.0.1 username: postal password: password vhost: postalvhost dns: # Specify the DNS records that you have configured. Refer to the documentation at # https://github.com/atech/postal/wiki/Domains-&-DNS-Configuration for further # information about these. mx_records: - mail.inlearn.in smtp_server_hostname: mail.inlearn.in spf_include: spf.mail.inlearn.in return_path: rp.mail.inlearn.in route_domain: routes.mail.inlearn.in track_domain: track.mail.inlearn.in smtp: # Specify an SMTP server that can be used to send messages from the Postal management # system to users. You can configure this to use a Postal mail server once the # your installation has been set up. host: 127.0.0.1 port: 2525 username: # Complete when Postal is running and you can password: # generate the credentials within the interface. from_name: Postal from_address: firstname.lastname@example.org rails: # This is generated automatically by the config initialization. It should be a random # string unique to your installation. secret_key: b73a7e04571431c601d19a7688418eb395d059c1ada525dcfd337e978236be759e278367fb7c6773be625265d3d235ee98b4f8405957e4bbd1c4001f367442bf531843f690a1918626179bf297e31d5cd268c2f33339afd19b17ce901a3832bb9a8107f04bf1b702a4da16096141ed5c46cee3f739d3adabf89fa3cfd91f00cf
Cross-check your config file and then save and close the file with CTRL + X.
Initializing Database is super easy, just execute the following command and you will see database tables were getting created in the output.
After that, it’s time to build postal
You will be asked for the email id, name, and password of the admin user. Type the answer and then go to the next step.
Starting & Running Postal
Starting and running postal is also super easy. Just run the following command.
You can check the status of postal
This is a new feature added by the Postal team to install SSL automatically.
docker run -d \ --name postal-caddy \ --restart always \ --network host \ -v /opt/postal/config/Caddyfile:/etc/caddy/Caddyfile \ -v /opt/postal/caddy-data:/data \ caddy
Now you can go to
http://mail.yourdomain.com:5000 and log in using admin credentials. You will see the admin page something like this.
In, the next article we will learn to create an organization, domain management, SMTP creation, etc.
Old installation guide
Installation and Configuration of MariaDB
First of all, install the MariaDB database on your server.
apt-get install mariadb-server libmysqlclient-dev -y
After installing MariaDB, it’s time to do some configuration to MariaDB
Answer all the questions as shown below:
Enter current password for root (enter for none): Set root password? [Y/n]: N Remove anonymous users? [Y/n]: Y Disallow root login remotely? [Y/n]: Y Remove test database and access to it? [Y/n]: Y Reload privilege tables now? [Y/n]: Y
Next login to MariaDB to create mysql database
mysql -u root -p
Enter your root password, then create a database and user for Postal. Here I am creating database name “postal” and database user “postaluser”. Also, replace postaluser password “your_password” with a password of your choice.
CREATE DATABASE postal CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'postaluser'@'localhost' IDENTIFIED BY 'your_password';
Next, grant all the privileges to the postal database:
GRANT ALL ON postal.* TO 'postaluser'@'localhost'; GRANT ALL PRIVILEGES ON `postal-%`.* to `postaluser`@`localhost` IDENTIFIED BY "password";
After that save and exit from the MariaDB shell
FLUSH PRIVILEGES; QUIT;
It’s time to install Ruby on the server. By default, Ruby is not available in the Ubuntu 18.04 default repository. Therefore, we need to add Ruby repository first.
apt-get install software-properties-common -y apt-add-repository ppa:brightbox/ruby-ng
Next, update the repository and install the Ruby.
apt-get update -y apt-get install ruby2.6 ruby2.6-dev build-essential -y
Now we need to install RabbitMQ for message queueing. For that, we need to install few dependencies.
apt-get install curl gnupg debian-keyring debian-archive-keyring apt-transport-https -y
Add signing keys and few repositories
sudo apt-key adv --keyserver "hkps://keys.openpgp.org" --recv-keys "0x0A9AF2115F4687BD29803A206B73A36E6026DFCA" curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | apt-key add - curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | apt-key add -
Now we need to add apt repositories maintained by Team RabbitMQ
sudo tee /etc/apt/sources.list.d/rabbitmq.list <<EOF deb https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main deb-src https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main deb https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu bionic main deb-src https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu bionic main EOF
After that update the repository and install Erlang.
apt-get update -y apt-get install -y erlang-base \ erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \ erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \ erlang-runtime-tools erlang-snmp erlang-ssl \ erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl
At last, install RabbitMQ.
apt-get install rabbitmq-server -y --fix-missing
Now we have RabbitMQ installed, let’s check the status of RabbitMQ
systemctl status rabbitmq-server
After that we need to create RabbitMQ vhost and user for postal. Simply run the following command:
rabbitmqctl add_vhost /postal rabbitmqctl add_user postal password rabbitmqctl set_permissions -p /postal postal ".*" ".*" ".*"
By default, the latest version of Nodejs is not available in the Ubuntu 18.04 default repository. Therefore, add the repository for that first.
curl -sL https://deb.nodesource.com/setup_12.x | bash
Next install it.
apt-get install nodejs -y
Before installing Postal, you will need to create a user for postal mail server on Ubuntu.
useradd -r -m -d /opt/postal -s /bin/bash postal
Now, enable ruby to listen on web ports.
setcap 'cap_net_bind_service=+ep' /usr/bin/ruby2.6
After that, install all the required gems with the following command:
gem install bundler
Next, install procodile with gem:
gem install procodile
Finally, install nokogiri with gem:
gem install nokogiri -v '1.7.2'
Install git with the following command
apt install git -y
Now, create a directory structure for Postal. Here all the files will be kept related to the Postal
mkdir -p /opt/postal/app
It’s time to download the latest version of Postal.
Once the download is completed, extract the downloaded file with the following command:
unzip -C /opt/postal/app
Next, change ownership of postal directory.
chown -R postal:postal /opt/postal
Now, create a symlink for Postal binary
ln -s /opt/postal/app/bin/postal /usr/bin/postal
After that, install all the required dependencies with the following command:
postal bundle /opt/postal/vendor/bundle
If above steps fails and you get the error, then execute the following command. This error is because mimemagic got updated.
cd /opt/postal/app bundle update mimemagic bundle install cd ~
Next, generate Postal Configuration files with the following command:
Now, open Postal configuration file and edit it to reflect correct information:
Make the following changes as per your environment:
web: host: postal.example.com # The protocol that requests to the management interface should happen on protocol: https main_db: # Specify the connection details for your MySQL database host: localhost username: postal password: password database: postal message_db: # Specify the connection details for your MySQL server that will be house the # message databases for mail servers. host: localhost username: postal password: password prefix: postal rabbitmq: # Specify the connection details for your RabbitMQ server. host: 127.0.0.1 username: postal password: password vhost: /postal dns: # Specifies the DNS record that you have configured. Refer to the documentation at # https://github.com/atech/postal/wiki/Domains-&-DNS-Configuration for further # information about these. mx_records: - mx.postal.example.com smtp_server_hostname: postal.example.com spf_include: spf.postal.example.com return_path: rp.postal.example.com route_domain: routes.postal.example.com track_domain: track.postal.example.com smtp: # Specify an SMTP server that can be used to send messages from the Postal management # system to users. You can configure this to use a Postal mail server once the # your installation has been set up. host: 127.0.0.1 port: 2525 username: # Complete when Postal is running and you can password: # generate the credentials within the interface. from_name: Postal from_address: email@example.com
Save and close the file with CTRL + X. Then, initialize database with the following command:
Next, you will need to create a admin user for Postal.
Answer all the questions as shown below:
Postal User Creator Enter the information required to create a new Postal user. This tool is usually only used to create your initial admin user. E-Mail Address : firstname.lastname@example.org First Name : Admin Last Name : Postal Initial Password: : ********* User has been created with e-mail address email@example.com
Finally, start the Postal application.
Now, check the status of Postal
Just in case, if you like to stop postal service, you can do so by
Create Systemd Service file for Postal
Next, you will need to create a systemd service file to manage Postal service. This can be done with the following command:
Add the following lines:
[Unit] Description=Postal Mail Platform After=mysql.service rabbitmq-server.service Wants=mysql.service rabbitmq-server.service [Service] ExecStart=/usr/bin/postal start ExecStop=/usr/bin/postal stop ExecReload=/usr/bin/postal restart User=postal Restart=on-failure Type=forking [Install] WantedBy=mysql.service rabbitmq-server.service
Save and close the file. Then, reload the systemd with the following command:
Next, start Postal service and enable it to start on boot with the following command:
systemctl start postal systemctl enable postal
You can check the status of Postal service with the following command:
systemctl status postal
Install and Configure Nginx
Next, you will need to install Nginx to access Postal mail server. First, install Nginx with the following command:
apt-get install nginx openssl -y
Next, copy Nginx configuration file with the following command:
cp /opt/postal/app/resource/nginx.cfg /etc/nginx/sites-available/default
Next, create a self-signed SSL certificate with the following command:
mkdir /etc/nginx/ssl/ openssl req -x509 -newkey rsa:4096 -keyout /etc/nginx/ssl/postal.key -out /etc/nginx/ssl/postal.cert -days 365 -nodes
Answer all the questions as shown below:
Generating a 4096 bit RSA private key ...............................++ .................++ writing new private key to '/etc/nginx/ssl/postal.key' ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:IN State or Province Name (full name) [Some-State]:Bihar Locality Name (eg, city) :Patna Organization Name (eg, company) [Internet Widgits Pty Ltd]:IT Organizational Unit Name (eg, section) :IT Common Name (e.g. server FQDN or YOUR name) :Dhiraj Email Address :firstname.lastname@example.org
Next, open the Nginx default virtual host file and define your domain:
Here, you need to make the following changes:
Save and close the file. After that, restart Nginx service with the following command:
systemctl restart nginx
Access Postal Web Interface
Now, open your web browser and type the URL
https://mail.yourdomain.com. You will be redirected to the admin page. Login with email id and password.
After that, you will postal dashboard.
In, next article we will learn to create organization, domain management and SMTP creation, etc.
Installing Postal is somewhat complex procedure. Nonetheless, it’s worth to give it a try considering the Postal features.