Production server setup
The default installation of Headwind MDM web panel is easy and makes it possible to study how open source MDM solution works. However it lacks several important features which may be required for the “production” server. Here’s what could be expected from the real on-premise MDM server:
- Use latest platform and OS version
- Use HTTPS secure connection
- Installed in the root of the domain
- APK files should be stored on the same server
Complete step-by-step setup instruction
Prerequisites
- Ubuntu 20.04 LTS server
- Public IP address
- Domain name bound to the public address (we used build.h-mdm.com)
The setup should be done as root.
Notice: in Headwind MDM version 4, steps 5-7 are performed automatically by the installer (./hmdm_install.sh), you do not need to do them manually any more!
1. Install required software
apt update apt install -y aapt tomcat9 postgresql vim
Notice: The version of Tomcat 9 installed by apt in Ubuntu 20.04 (9.0.31) has a HTTPS-related bug, and Headwind MDM doesn’t work properly with HTTPS.
The solution would be either to use Ubuntu 18.04 or to update Tomcat manually to the latest version.
To view the Tomcat version, run the command:
/usr/share/tomcat9/bin/version.sh
To update Tomcat to the suitable version (in the example, the latest version is 9.0.40), execute the following commands:
VERSION=9.0.40
wget https://archive.apache.org/dist/tomcat/tomcat-9/v9.0.40/bin/apache-tomcat-${VERSION}.tar.gz
tar -zxf apache-tomcat-${VERSION}.tar.gz
cd apache-tomcat-${VERSION}
chmod a+x bin
chmod a+x lib
chmod -R a+r bin
chmod -R a+r lib
chmod a+x bin/*.sh
mv /usr/share/tomcat9/bin /usr/share/tomcat9/bin~
mv /usr/share/tomcat9/lib /usr/share/tomcat9/lib~
cp -r bin /usr/share/tomcat9
cp -r lib /usr/share/tomcat9
service tomcat9 restart
Note that apt on Ubuntu 20.10 installs Tomcat version 9.0.37-3 which is fine.
2. Setup the database
su postgres psql postgres=# CREATE USER hmdm WITH PASSWORD 'topsecret'; postgres=# CREATE DATABASE hmdm WITH OWNER=hmdm; postgres=# \q exit
Notice: you may wish to use your own password for better security. Do not forget to remember it and use at step 4 when running a Headwind MDM installation script.
3. Build Headwind MDM
git clone https://github.com/h-mdm/hmdm-server.git cd hmdm-server/ apt install -y maven mvn install
Alternative: download and unzip the binary installer
Notice: get the URL of the latest web installer version on the “Download” page.
wget https://h-mdm.com/files/hmdm-3.33-install-ubuntu.zip apt install -y unzip unzip hmdm-3.33-install-ubuntu.zip cd hmdm-install/
4. Install Headwind MDM
./hmdm_install.sh
Important: on Tomcat 9, you need to use a special directory instead of the one suggested by the installer.
To install to the root of the domain, type ROOT when the installer prompts for the subdirectory. Also, leave the “port” empty to use default HTTPS port (443).
After this step, you can already check that Headwind MDM web panel can be opened by opening http://build.h-mdm.com:8080 in a web browser. This was a final step of the “test” setup, but we need to go further if our goal is a production server.
If you got any issues while installing Headwind MDM, you need to look into Tomcat logs to diagnose the problem. Tomcat 9 writes its logs to the system log of Linux:
journalctl -u tomcat9.service
Make a backup of your XML configuration file!
There is a bug in Tomcat 9 which causes occasional removal of the XML configuration after updating the WAR file. To avoid the server fault after upgrading, we strongly recommend to make a backup.
cp /var/lib/tomcat9/conf/Catalina/localhost/ROOT.xml /var/lib/tomcat9/conf/Catalina/localhost/ROOT.xml~
5. Setup HTTPS via LetsEncrypt
Notice: LetsEncrypt is a free certificate which needs to be renewed each 3 months. You may wish to use another HTTPS certificate. Please read how to install it here.
5.1. Obtain the certificate
apt install -y certbot vim ./letsencrypt-ssl.sh
We presume you know how to use a vim editor. You can use any other text editor or read about vim here.
Change one line in the letsencrypt-ssl.sh:
DOMAIN=your-domain.com -> DOMAIN=build.h-mdm.com
After updating the script, you can run it and get the certificate (answer LetsEncrypt questions when it asks for).
./letsencrypt-ssl.sh
5.2. Add HTTPS to the Tomcat configuration
Look at the output of letsenscrypt-ssl.sh. Tomcat configuration file server.xml already contains a commented entry for the HTTPS connector. You need to uncomment it and setup the path to the keystore file and the keystore password.
vim /var/lib/tomcat9/conf/server.xml
After you’re done, restart Tomcat to apply the changes.
service tomcat9 restart
To test this step, you can try to open https://build.h-mdm.com:8443 in a web browser.
5.3. Setup the automatic certificate renewal
LetsEncrypt requires the certificate renewal each 3 months. To avoid service interruption, you may wish to renew them more frequently. We suggest to run the automatic renewal script each week.
To run the certificate renewal script each week, add the following line to crontab (use “crontab -e” command):
0 5 * * 1 /root/hmdm-server/letsencrypt-ssl.sh
The numbers in this line denote the minute, hour and weekday the script is executed. In this example, the script is executed on Monday 5 am.
Notice: check the path to the script! You may wish to copy the script to a common directory like /usr/local/bin
6. Setup the default SSL port
Tomcat is accepting HTTPS requests on port 8443. To redirect the default HTTPS port 443 to 8443, use iptables.
Notice: these instructions will work only if your server has a public IP address. If your server is behind the NAT, you may need to setup your firewall instead (here’s how to).
Create a file, for example, /etc/iptables-tomcat.sh and add the following lines.
/sbin/iptables -A PREROUTING -t nat -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 8443 /sbin/iptables -A OUTPUT -t nat -o lo -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 8443
Grant the executable permissions to the file and execute it:
# chmod +x /etc/iptables-tomcat.sh # /etc/iptables-tomcat.sh
To make iptables setup permanent, mark the script to be called at boot by adding the following line to the crontab file:
@reboot /etc/iptables-tomcat.sh
To modify crontab, use the command “crontab -e”.
7. Open Headwind MDM web panel
This step finalizes the installation. You need to perform some tests to make sure Headwind MDM is working well, and upload the required mobile application (APK) files from their default location to your server.
7.1. Make sure URL is working
https://build.h-mdm.com should now open the web panel.
The default login and password is admin:admin (do not forget to change it by clicking admin in the top right corner, then Profile!)
7.2. Upload APK files to your server
Headwind MDM installer setups your web panel so it gets the required APKs from the https://h-mdm.com website. In most cases, you may wish to store them on your server.
Select the Applications tab and unset the “Show system applications” checkbox. You will see the links pointing to h-mdm.com. Copy the link and save the file to your local computer.
Click Add to upload a file to your server.
After clicking “Save”, Headwind MDM will ask you whether you want to add a new application or a new version. Select “New version” to overwrite the default location pointing to h-mdm.com.
On the last screen, you do not need to change anything. Just click “Save”.
Repeat this procedure for each APK file.
7.3. Check the enrollment QR code
Open the Devices section and click the QR code icon.
If you see the QR code, Headwind MDM installation is completed, congratulations!
You may proceed with the device enrollment. See this video how to enroll the device: