provide one installation script that sets up everything for usage

.gitignore

@@ -17,3 +17,5 @@ Thumbs.db
 ms.env
 configs/vars/vault.yml
 mail/
+# created by using the install script
+docker-mailserver/

LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Kristi Jorgji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,22 +1,83 @@
 # docker-mailserver
 
-================
-!!! WORK IN PROGRESS !!!
-================
+[![ci::status]][ci::github] [![docker::pulls]][docker::hub] 
 
-Docker image that will provide out of the box mailserver using
+[ci::status]: https://img.shields.io/github/workflow/status/kristijorgji/docker-mailserver/Publish?color=blue&label=CI&logo=github&logoColor=white&style=for-the-badge
+[ci::github]: https://github.com/kristijorgji/docker-mailserver/actions
+[docker::pulls]: https://img.shields.io/docker/pulls/kristijorgji/docker-mailserver.svg?style=for-the-badge&logo=docker&logoColor=white
+[docker::hub]: https://hub.docker.com/r/kristijorgji/docker-mailserver/
+
+1. [About](#about)
+2. [Requirements](#requirements)
+3. [How to use](#how-to-use)
+4. [How to develop locally](#how-to-develop-locally)
+5. [How to test and troubleshoot the setup](docs/how-to-test-and-troubleshot-the-setup.md)
+
+# About
+
+A docker image that will provide an out of the box mailserver using
 
 * postfix
 * dovecot
-* IMAP and POP so you can use mail clients like Thunderbolt with ease
-* roundcube UI to send and check the received emails
+* IMAP and POP with mysql driver so you can use mail clients like Thunderbird with ease
+* Multiple domains supported, you can have send or receive emails coming for both [email protected] and [email protected]
+* roundcube UI to send and check the received emails [WIP] 
+
+# Requirements
+
+**Tools**
+- [Docker](https://www.docker.com/) installed
+- [Docker compose](https://docs.docker.com/compose/) installed
+
+**Prerequisites** 
+- Your **mx record** points to the machine where you will use this docker mailserver will run
+  - ![MX Record Namescheap Example](./docs/mx-record-example.png)
+- Your _mailserver domain_ **A record (or cname)** points to the machine where  this docker mailserver will run.
+  - ![CNAME Mailserver Domain Record Namescheap Example](./docs/maildomain-cname-example.png)
+- Your webserver is configured to listen for your _mailserver domain_ port 80, so letsencrypt can generate and renew the ssl certificate
+- You need to expose the required ports through your security groups/firewall in order to connect to the mailserver.  
+  - 25     # smtp
+  - 465    # smtps
+  - 110    # pop3
+  - 143    # imap
+  - 993    # imaps
+  - 995    # pop3s
+
+**System requirements**
+
+**Recommended**:
+
+- 1 Core
+- 2GB RAM
+- Swap enabled for the container
+
+**Minimum**:
+
+- 1 vCore
+- 512MB RAM
+- You'll need to deactivate some services like ClamAV to be able to run on a host with 512MB of RAM. Even with 1G RAM you may run into problems without swap
 
 # How to use
 
-TODO COMING SOON the docker image after published
+First execute the following command to download and install the tool.
+You can change `docker-mailserver` in the third line with whatever path you want for the install
+
+```shell
+curl -LJO https://raw.githubusercontent.com/kristijorgji/docker-mailserver/main/install.sh \
+ && chmod a+x install.sh \
+ && ./install.sh docker-mailserver
+```
+
+After the installation you will see a message of what configurations you can make before starting the docker container of the mailserver
+
+You can modify those variables to your wishes, those involve things like
+* your mailserver domain name
+* your mailserver supported domains (can have more than one)
+* your mailserver users
+* etc
+
+If you want to make more changes to the configurations of postfix/dovecot or any tool, just modify the `jinja2` templates at configs folder after the tool installs the mailserver.
 
-The client of this project needs to change only the mounted `configs` folder where they have full control of postfix, dovecot templates they would like to change
-as well as all the vars passed
 
 Everything else is auto-generated during the start of the container including the self signed ssl certificates with the domain name provided
 The provisioning is done via ansible and jinja2 templates, that is why the configuration templates end in `.j2` extension
@@ -25,8 +86,6 @@ The provisioning is done via ansible and jinja2 templates, that is why the confi
 
 Run `make ress` to create a docker image and log into one container created from the created image
 
-Make sure that configs/vars/vars.yml `env` is set to `local`
-
 Afterward you can execute the boot provisioning by going to 
 `cd /dev-docker-data`
 

configs/vars/local.yml

@@ -0,0 +1,5 @@
+---
+
+# the variables here are used only while developing locally this tool
+
+env: local

configs/vars/vars.yml

@@ -1,8 +1,5 @@
 ---
 
-# comment this when deploying to production. It is used only during development as local
-env: local
-
 mail_server_cert_path: "/etc/letsencrypt/live/{{ mail_server_hostname }}/cert.pem"
 mail_server_pem_path: "/etc/letsencrypt/live/{{ mail_server_hostname }}/cert.pem"
 mail_server_key_path: "/etc/letsencrypt/live/{{ mail_server_hostname }}/privkey.pem"

docker-compose.release.yml

@@ -0,0 +1,16 @@
+version: "3.7"
+
+services:
+  ms:
+    image: ${MAILSERVER_IMAGE}
+    volumes:
+      - ./configs:/configs
+      - ./${MAILSERVER_MAILS_PATH}:/var/mail
+    ports:
+      - "25:25"       # smtp
+      - "465:465"     # smtps
+      - "110:110"     # pop3
+      - "143:143"     # imap
+      - "993:993"     # imaps
+      - "995:995"     # pop3s
+    container_name: ms

docker-compose.yml

@@ -11,6 +11,9 @@ services:
       - ./mail:/var/mail
     ports:
       - "25:25"       # smtp
+      - "465:465"     # smtps
       - "110:110"     # pop3
       - "143:143"     # imap
+      - "993:993"     # imaps
+      - "995:995"     # pop3s
     container_name: ms

install.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+
+function print_usage() {
+	echo "Usage: $(basename $0) <PATH>"
+	echo
+	echo '  <PATH>                       The path where to install the project, defaults to docker-mailserver'
+}
+
+# Resource: https://stackoverflow.com/a/5947802
+color_green='\033[0;32m' # Green
+color_red='\033[0;31m' # Red
+color_blue='\033[0;34m' # Blue
+color_yellow='\033[0;33m' # Yellow
+color_cyan='\033[0;36m' # Cyan
+color_reset='\033[0m' # No Color
+
+function print_error {
+  msg=${1:-'no message'}
+  printf "${color_red}[ERROR] ${msg}${color_reset}\n" >&2
+}
+
+function print_success {
+  msg=${1:-'no message'}
+  printf "${color_green}[SUCCESS] ${msg}${color_reset}\n"
+}
+
+if [ "${#}" -ne '1' ]; then
+	print_error 'Wrong number of arguments'
+	print_usage
+	exit 1
+fi
+
+destdir=${1:-docker-mailserver}
+
+gh_username=kristijorgji
+gh_repository=docker-mailserver
+repository="https://github.com/$gh_username/$gh_repository"
+
+# install required tools like jq
+if ! command -v jq &> /dev/null
+then
+  echo "Will install required tool jq"
+  which -s brew
+  if [[ $? != 0 ]] ; then
+      # brew is not installed
+      apt-get install jq -y
+  else
+      brew install jq
+  fi
+fi
+
+echo -e "Getting last tag of the repository $repository \n"
+tag=$(curl -s "https://api.github.com/repos/$gh_username/$gh_repository/tags"  | jq -r '.[0].name')
+echo "Last tag is $tag"
+
+if [ ! -d $destdir ]
+then
+    mkdir -p $destdir
+fi
+
+echo -e "Downloading last tag $tag then extracting"
+filename="$tag.tar.gz"
+curl -LO "$repository/archive/refs/tags/$filename"
+tar zxvf "$filename" -C "$destdir" --strip-components=1
+rm "$filename"
+
+echo -e "Setting up the project"
+
+rm -rf "$destdir/.github"
+rm -rf "$destdir/ci"
+rm -rf "$destdir/docker-data"
+rm -rf "$destdir/docs"
+rm -rf "$destdir/tests"
+rm "$destdir/.gitignore"
+rm "$destdir/docker-compose.yml"
+rm "$destdir/Dockerfile"
+rm "$destdir/Makefile"
+rm "$destdir/README.md"
+rm "$destdir/install.sh"
+rm "$destdir/configs/vars/local.yml"
+
+mv "$destdir/configs/vars/vault.example.yml" "$destdir/configs/vars/vault.yml"
+mv "$destdir/docker-compose.release.yml" "$destdir/docker-compose.yml"
+
+
+cat <<EOT >> "$destdir/configs/vars/vars.yml"
+
+# everything below is added by the installation script
+
+env: production
+EOT
+
+cat <<EOT > "$destdir/.env"
+# this env file is used by docker-compose
+
+MAILSERVER_IMAGE=kristijorgji/docker-mailserver:$tag
+MAILSERVER_MAILS_PATH=./mail
+EOT
+
+__msg="
+Congratulations, installation was successful!
+Before starting the container via docker-compose you need to edit the following files with your configuration variables:
+  $destdir/configs/vars/vars.yml
+  $destdir/configs/vars/vault.yml
+  $destdir/.env
+
+Afterward do the following:
+cd $destdir
+docker-compose up -d
+
+That is all, in a couple of minutes the mailserver will be up and running!
+
+You can follow the logs via docker-compose logs -f ms
+"
+print_success "$__msg"