lightsail-miab-installer is a user-friendly command-line tool designed to streamline the setup of Mail-in-a-Box (a comprehensive mail server package) on Amazon Lightsail. This installer is configured to integrate with Amazon S3 for backups and Amazon SES for email sending (relay), it offers a quick and efficient way to host your own email solution.
To begin installation, run the following command.
sh lightsail-miab-installer.sh \
--installation-id demo \
--az ap-southeast-1a \
--email [email protected] \
--hostname box.example.com
Your mail server should up and running in few minutes, and you can access it using a web interface. By default it will be installed on $5 USD/mo Amazon Lightsail instance.
All the data in your Amazon S3 bucket will be preserved, allowing you to restore it on another machine if needed. Additionally, you have the option to delete the stack using the CloudFormation web console or AWS CLI.
- Requirements
- Installation
- Usage and Examples
- Post installation
- FAQ
- Changelog
- Todo
- Credits
- Contributing
- License
Prerequisites for running this script:
- An active AWS account with sufficient permissions.
- AWS CLI v2.
- SSH client
- Basic shell utilities such as
awk aws base64 cat cut date openssl sed ssh tee tr wc
- jq
lightsail-miab-installer has been tested using following shells:
- bash v4.2 (Linux)
- zsh v5.8.1 (macOS, Linux)
Download the archive or clone the repository.
curl -o 'lightsail-miab-installer.zip' -s -L https://github.com/rioastamal/lightsail-miab-installer/archive/refs/heads/main.zip
unzip lightsail-miab-installer.zip
cd lightsail-miab-installer-main/
Running lightsail-miab-installer with --help flag will gives you list of options and examples.
sh lightsail-miab-installer.sh --help
Usage: lightsail-miab-installer.sh [OPTIONS]
Where OPTIONS:
--az AZ Instance availability zone specified by AZ. Default to
'us-east-1a'.
--destroy Destroy installation specified by --installation-id.
--disable-s3-backup Do not configure Mail-in-a-Box to backup mailserver
data to Amazon S3.
--disable-smtp-relay Do not configure Postfix to use Amazon SES as SMTP
relay.
--dry-run Dry run mode, print CloudFormation template and exit.
--email EMAIL Mail-in-a-Box administrator email specified by EMAIL.
An example '[email protected]'.
--help Print this help and exit.
--hostname HOSTNAME Mail-in-a-Box primary hostname specified by HOSTNAME.
An example 'box.example.com'.
--installation-id ID Installation identifier by ID, e.g 'demo'.
--instance-type TYPE Amazon Lightsail plan specified by TYPE. Valid value:
'5_usd', '10_usd', '20_usd', '40_usd', '80_usd', or
'160_usd'. Default is '5_usd'.
--password PASSWD Mail-in-a-Box administrator password specified by
PASSWD.
--restore Restore installation data from backup which stored on
S3 bucket. See --restore-help for more info.
--restore-help Print help information how to restore from backup.
--version Print script version.
--------------------------- lightsail-miab-installer ---------------------------
lightsail-miab-installer is a powerful command line tool powered by
Mail-in-a-Box, designed to simplify the setup of a complete mail server on
Amazon Lightsail.
lightsail-miab-installer is free software licensed under MIT. Visit the project
homepage at http://github.com/rioastamal/lightsail-miab-installer.
Command below will install Mail-in-a-Box on $5/mo Amazon Lightsail instance (1 RAM), Availability Zone ap-southeast-1c
- Asia Pasific (Singapore), box.example.com
as hostname, [email protected]
as Administrator's email and lightsaildemo123
as Administrator's password.
sh lightsail-miab-installer.sh \
--installation-id demo \
--az ap-southeast-1c \
--hostname box.example.com \
--email '[email protected]' \
--password 'lightsaildemo123'
Here, I am specifying demo
as installation id, and the corresponding CloudFormation stack name would be miab-demo
.
Although you can access the server via its IP address, it is necessary to specify a hostname. This allows Mail-in-a-Box to generate SSL certificates for you. Having SSL certificates for your box prevents any warnings when accessing your Admin panel from a web browser or when making API calls.
To specify hostname you can use --hostname
option.
sh lightsail-miab-installer.sh \
--installation-id demo \
--az ap-southeast-1c \
--hostname box.example.org \
--email '[email protected]' \
--password 'lightsaildemo123'
Mail-in-a-box recommends using box
subdomain when configuring the hostname. For example, if your domain is example.org
you can specify box.example.org
as the hostname.
To be able to use Mail-in-a-Box you need to specify Administrator's email and password for accessing Admin panel and to calls API. You can specify email using --email
and password using --password
option.
sh lightsail-miab-installer.sh \
--installation-id demo \
--az ap-southeast-1c \
--hostname box.example.com \
--email '[email protected]' \
--password 'MyEmailServer123'
Domain of the email doesn't have to be the same as the hostname.
Default Lightsail plan used is $5 USD/mo with 1GB of RAM and 40GB of SSD disk. If you want to change this, you can specify using --instance-type
option.
sh lightsail-miab-installer.sh \
--installation-id demo \
--az ap-southeast-1c \
--hostname box.example.com \
--email '[email protected]' \
--password 'lightsaildemo123' \
--instance-type 20_usd
Command above will use $20/mo plan, which offers 4GB of RAM, 2 Core CPU and 80GB SSD disk. You can find details about all available plans on the Amazon Lightsail pricing page.
Default availability zone is us-east-1a
. To change the availability zone you can use --az
option, e.g eu-west-1a
Europe (Ireland).
sh lightsail-miab-installer.sh \
--installation-id demo \
--az eu-west-1 \
--hostname box.example.com \
--email '[email protected]' \
--password 'lightsaildemo123' \
--instance-type 20_usd
To restore from backup, you need to specify several configurations from previous installation:
- Amazon S3 buckets that are used to store the mail backup and Nextcloud data
- Mail-in-a-Box backup secret key can be found on your old box machine at
/home/user-data/backup/secret_key.txt
or in the AWS SSM Parameter Store at/MailInABox/miab-[INSTALLATION_ID]/BackupSecretKey
.
export LMIAB_BACKUP_SECRET_KEY='_YOUR_BACKUP_SECRET_KEY_'
export LMIAB_MAIL_BACKUP_BUCKET='_YOUR_OLD_MAIL_BACKUP_BUCKET_'
export LMIAB_NEXTCLOUD_BACKUP_BUCKET='_YOUR_OLD_NEXTCLOUD_BACKUP_BUCKET_'
Add --restore
option when creating new box.
sh lightsail-miab-installer.sh \
--installation-id new-demo \
--az ap-southeast-1c \
--hostname new-box.example.com \
--email '[email protected]' \
--password 'lightsaildemo123' \
--restore
Assuming that you will use your old IP address for your new box, you need to add a DNS A record of new-box.example.com
to point to your old IP. Afterward, on the Amazon Lightsail instance, you should detach the static IP from the old box and assign it to the new one.
You have two options to destroy your Mail-in-a-Box installation which was installed by lightsail-miab-installer. You can use --destroy
option as shown in the example below.
sh lightsail-miab-installer.sh \
--installation-id demo \
--az ap-southeast-1c \
--destroy
There will be a confirmation, you need to type "yes" to destroy.
This action will destroy CloudFormation stack 'demo' (ap-southeast-1).
Type 'yes' to continue:
To execute the script in dry run mode, use the --dry-run
option. This will print the CloudFormation template and then exit. Running the script in this mode can be beneficial for inspecting the resources that will be created.
sh lightsail-miab-installer.sh \
--installation-id demo \
--az eu-west-1 \
--hostname box.example.com \
--email '[email protected]' \
--password 'lightsaildemo123' \
--instance-type 20_usd \
--dry-run
After the installation, there are a few things you should check:
- Ensure that the nameserver of your domain is correctly pointing to the box. The process of changing the nameserver depends on your DNS provider. Refer to your DNS provider's documentation for instructions.
- Provision SSL certificates by logging into the Admin panel and navigating to System > TLS (SSL) Certificates. Then, click the Provision button.
- Verify that your domain is successfully verified on Amazon SES before sending any emails. You can find more details in the "Verified identities" section of Amazon SES. Note that the verification process may take several minutes. If it takes too long, you can try removing the identity and creating a new one.
- For production use, if your Amazon SES account is still in sandbox mode, it is necessary to request the removal of sandbox restrictions for your account.
- If you are using an external DNS service for your domain, verify that the related DNS records, such as MX, SPF, DKIM, and DMARC settings, are properly configured. These settings are crucial for email delivery and security. Ensure they are accurately set according to the guidelines provided by your DNS service or in the Mail-in-a-Box documentation.
Check the rejection messages for specific reasons and review the mail server logs at /var/log/mail.log
or /var/log/syslog
for further insights.
There several reason for this.
-
Make sure your MX record is pointing to the box. You can use online DNS lookup tool or from command line.
dig +short example.com MX
It should output the address of servers which responsible for handling the email delivery.
10 box.example.com.
-
Check mail server log at
/var/log/mail.log
or/var/log/syslog
for more details. -
Make sure firewall for incoming port 25 is open both on OS and on Amazon Lightsail instance.
See the log file at .out/[REGION]-[CLOUDFORMATION_STACK_NAME]-[TIME].log
. If you did not find the issue then open CloudFormation console. Most of the time this is caused by CloudFormation failed to create a resource such as failed to create Amazon Lightsail Instance due permission issue or you do not have enough quota.
Yes it is totally safe. It will destroy all resources created by lightsail-miab-installer.
lightsail-miab-installer uses SSH to connect to node in Kubernetes to perform tasks. If your SSH key having a passphrase it may quite annoying to enter the passphrase multiple times during installation process.
One of the solution is by using ssh-agent and ssh-add. Before running the installation, issue command below.
eval $( ssh-agent )
ssh-add /path/to/your/ssh-private.key
- Added support for new shell: zsh
- Added support for macOS
- Automatic restore from S3 backup
- Initial release candidate
- Automatically generate TLS certificates for main domain
- Automatically restore from S3 backup
- Test on different shells (dash,
zsh)
This project is heavily inspired from:
- Fully Automated Deployment of an Open Source Mail Server on AWS by Michael Meidlinger and David Schwendemann.
- aws-samples/aws-opensource-mailserver
Fork this repo and send me a PR.
This project is licensed under MIT License.