How can we help?


atmail suite upgrade guide

Dominic -


How can I upgrade my atmail suite installation?


  • atmail suite


atmail needs to be upgraded to the latest version.


Keeping your atmail installation up-to-date should be prioritized so your system can benefit from our latest technologies and security features. You can find all the latest and greatest changes in the changelog.

Pre-Upgrade Tasks

  1. Ascertain current version. The api and webmail packages will represent the current version of your suite.
    [root@a8 ~]# rpm -qa | grep atmail-'webmail\|api'
  2. Backup database.
    [root@a8 ~]# mysqldump -u root -p -d apiserver > apiserver-`rpm -qa atmail-api | sed 's/-/ /g' | awk '{print $3}'`_`date +"%Y%m%d"`.sql
  3. Backup both the apiserver and webmail. For your convenience the following command will create a suite-version_date.tgz
    [root@a8 ~]# tar cfvz suite-`rpm -qa | grep atmail-webmail | sed 's/-/ /g' | awk '{print $3}'`_`date +"%Y%m%d"`.tgz apiserver[version_date].sql /etc/atmail/api /etc/atmail/webmail /etc/nginx/conf.d/atmail-api.locations /etc/nginx/conf.d/atmail-webmail.locations /var/lib/atmail/api /usr/share/atmail/webmail
    -rw-r--r--. 1 root root  1914825 Jul 21 17:04 suite-8.0.0_20170721.tgz

This is required before you upgrade in case you need to roll-back any changes, please do not skip this step.

Upgrade your atmail suite.

  1. You can download your latest atmail suite by directly accessing your customer portal.
  2. Extract the atmail-suite-rpm.tar.gz package.
    [root@8 tmp]# tar xvzf atmail-suite-rpm.tar.gz
  3. Enter the atmail-suite directory.
    [root@8 tmp]# cd atmail-suite-[version]
    [root@8 atmail-suite-[version]]#
  4. Update your rpm's using yum. The use of the wildcard (*) in the working directory will allow yum to determine which specific rpm's will be updated. In this case, you can see the api, dav and webmail rpm's will be updated.
    [root@a8 atmail-suite-8.1.1]# yum update *.rpm
    Loaded plugins: fastestmirror
    Repodata is over 2 weeks old. Install yum-cron? Or run: yum makecache fast
    Examining atmail-api-8.1.1-1.el7.centos.x86_64.rpm: atmail-api-8.1.1-1.el7.centos.x86_64
    Marking atmail-api-8.1.1-1.el7.centos.x86_64.rpm as an update to atmail-api-8.0.0-1.el7.centos.x86_64
    Examining atmail-common-1.0.0-1.el7.centos.x86_64.rpm: atmail-common-1.0.0-1.el7.centos.x86_64
    atmail-common-1.0.0-1.el7.centos.x86_64.rpm: does not update installed package.
    Examining atmail-dav-1.0.1-1.el7.centos.x86_64.rpm: atmail-dav-1.0.1-1.el7.centos.x86_64
    Marking atmail-dav-1.0.1-1.el7.centos.x86_64.rpm as an update to atmail-dav-1.0.0-1.el7.centos.x86_64
    Examining atmail-webmail-8.1.1-1.el7.centos.x86_64.rpm: atmail-webmail-8.1.1-1.el7.centos.x86_64
    Marking atmail-webmail-8.1.1-1.el7.centos.x86_64.rpm as an update to atmail-webmail-8.0.0-1.el7.centos.x86_64
    Resolving Dependencies
    --> Running transaction check
    ---> Package atmail-api.x86_64 0:8.0.0-1.el7.centos will be updated
    ---> Package atmail-api.x86_64 0:8.1.1-1.el7.centos will be an update
    ---> Package atmail-dav.x86_64 0:1.0.0-1.el7.centos will be updated
    ---> Package atmail-dav.x86_64 0:1.0.1-1.el7.centos will be an update
    ---> Package atmail-webmail.x86_64 0:8.0.0-1.el7.centos will be updated
    ---> Package atmail-webmail.x86_64 0:8.1.1-1.el7.centos will be an update
    --> Finished Dependency Resolution

    Dependencies Resolved

     Package                                      Arch                                 Version                                             Repository                                                               Size
     atmail-api                                   x86_64                               8.1.1-1.el7.centos                                  /atmail-api-8.1.1-1.el7.centos.x86_64                                   5.5 M
     atmail-dav                                   x86_64                               1.0.1-1.el7.centos                                  /atmail-dav-1.0.1-1.el7.centos.x86_64                                   5.6 M
     atmail-webmail                               x86_64                               8.1.1-1.el7.centos                                  /atmail-webmail-8.1.1-1.el7.centos.x86_64                               4.0 M

    Transaction Summary
    Upgrade  3 Packages

    Total size: 15 M
    Is this ok [y/d/N]: y
    Downloading packages:
    Running transaction check
    Running transaction test
    Transaction test succeeded
    Running transaction
      Updating   : atmail-dav-1.0.1-1.el7.centos.x86_64                                                                                                                                                              1/6
      Updating   : atmail-api-8.1.1-1.el7.centos.x86_64                                                                                                                                                              2/6
      Updating   : atmail-webmail-8.1.1-1.el7.centos.x86_64                                                                                                                                                          3/6
    Setting JMAP_API_URI to ..... [ OK ]
    Setting Base HREF to / ..... [ OK ]
      Cleanup    : atmail-dav-1.0.0-1.el7.centos.x86_64                                                                                                                                                              4/6
      Cleanup    : atmail-api-8.0.0-1.el7.centos.x86_64                                                                                                                                                              5/6
      Cleanup    : atmail-webmail-8.0.0-1.el7.centos.x86_64                                                                                                                                                          6/6
      Verifying  : atmail-webmail-8.1.1-1.el7.centos.x86_64                                                                                                                                                          1/6
      Verifying  : atmail-api-8.1.1-1.el7.centos.x86_64                                                                                                                                                              2/6
      Verifying  : atmail-dav-1.0.1-1.el7.centos.x86_64                                                                                                                                                              3/6
      Verifying  : atmail-dav-1.0.0-1.el7.centos.x86_64                                                                                                                                                              4/6
      Verifying  : atmail-webmail-8.0.0-1.el7.centos.x86_64                                                                                                                                                          5/6
      Verifying  : atmail-api-8.0.0-1.el7.centos.x86_64                                                                                                                                                              6/6

      atmail-api.x86_64 0:8.1.1-1.el7.centos                               atmail-dav.x86_64 0:1.0.1-1.el7.centos                               atmail-webmail.x86_64 0:8.1.1-1.el7.centos                              


  5. Please Note:
    If upgrading from version 8.1.1. to 8.2.0 and are using the default self-signed certificate generated upon installation, you will need to add the following to your /etc/atmail/api/api.conf.

    Restart and check the status of the apiserver.
    [root@a8 ~]# systemctl restart apiserver
    [root@a8 ~]# systemctl status apiserver
    ● apiserver.service - atmail-api - jmap api for atmail webmail
       Loaded: loaded (/usr/lib/systemd/system/apiserver.service; enabled; vendor preset: disabled)
      Drop-In: /etc/systemd/system/apiserver.service.d
       Active: active (running) since Fri 2017-07-21 14:35:33 AEST; 3s ago
      Process: 9839 ExecStop=/bin/kill -s QUIT $MAINPID (code=exited, status=0/SUCCESS)
     Main PID: 9841 (apiserver)
       CGroup: /system.slice/apiserver.service
               └─9841 /usr/bin/apiserver -config /etc/atmail/api/api.conf

    Jul 21 14:35:33 a8 systemd[1]: Started atmail-api - jmap api for atmail webmail.
    Jul 21 14:35:33 a8 systemd[1]: Starting atmail-api - jmap api for atmail webmail...


If you encounter any issues trying to restart your apiserver, use the following command to log to std out. The output below shows an example of an error occurring and how to remedy it.

[root@a8 atmail-suite-8.2.0]# /usr/bin/apiserver -c /etc/atmail/api/api.conf -V -console
INFO[0000] Migrations path: /var/lib/atmail/api/resources/migrations/
INFO[0000] Migrations table found
INFO[0000] Migration file found: /var/lib/atmail/api/resources/migrations/1_V800_down.sql
INFO[0000] Migration file found: /var/lib/atmail/api/resources/migrations/1_V800_up.sql
INFO[0000] Migration file found: /var/lib/atmail/api/resources/migrations/2_V800_down.sql
INFO[0000] Migration file found: /var/lib/atmail/api/resources/migrations/2_V800_up.sql
INFO[0000] Migration file found: /var/lib/atmail/api/resources/migrations/3_V800_down.sql
INFO[0000] Migration file found: /var/lib/atmail/api/resources/migrations/3_V800_up.sql
INFO[0000] Invalid migration file found: /var/lib/atmail/api/resources/migrations/README
INFO[0000] Migrations file pairs found: 3
There are 1 schema changes waiting to be applied.
Please backup your database and re-run the apiserver with the flag --updatedb.

In referring to the case above, you can resolve this issue by performing the following:

  1. Backup your database.
    [root@a8 ~]# mysqldump -u root -p -d apiserver > apiserver-`rpm -qa atmail-api | sed 's/-/ /g' | awk '{print $3}'`_`date +"%Y%m%d"`.sql
  2. Run the apiserver executable with the --updatedb argument and confirm the apiserver starts.
    [root@a8 atmail-suite-8.2.0]# /usr/bin/apiserver -c /etc/atmail/api/api.conf --updatedb -V -console
    INFO[2017-10-09T18:50:58+11:00] atmail API server version: 8.2.0
    INFO[2017-10-09T18:50:58+11:00] Starting API Server Listening on
    INFO[2017-10-09T18:50:58+11:00] Starting API Server Event Source Listening on
  3. Once you can confirm functionality, start the service normally with systemd.
    [root@a8 atmail-suite-8.2.0]# systemctl start apiserver
    [root@a8 atmail-suite-8.2.0]# systemctl status apiserver
    ● apiserver.service - atmail-api - jmap api for atmail webmail
    Loaded: loaded (/usr/lib/systemd/system/apiserver.service; enabled; vendor preset: disabled)
    Active: active (running) since Mon 2017-10-09 18:51:12 AEDT; 3s ago
    Process: 3802 ExecStop=/bin/kill -s QUIT $MAINPID (code=exited, status=1/FAILURE)
    Main PID: 3873 (apiserver)
    CGroup: /system.slice/apiserver.service
    └─3873 /usr/bin/apiserver -config /etc/atmail/api/api.conf
Have more questions? Submit a request


Contact our support team

+61 (7) 5357 6605