The system consists of the server part and the agent application.
The agent is a regular Android application and is available for download on Google Play.
The server part is delivered as the Docker-Compose container and works on any Linux. The installer is optimized for Ubuntu Linux (16.04 or above, 20.04 recommended), also CentOS 8 is supported. To support other Linux distros, some adjustments to the installer configuration must be done (please contact us for details).
To install aPuppet server, setup a domain (a subdomain would be enough).
The server needs root access and it is recommended to use Ubuntu Linux 20.04 LTS.
The following TCP/IP ports must be enabled on a firewall (or forwarded if you’re using NAT):
- 80/TCP – used only by certbot to renew certificates;
- 443/TCP – used by nginx to display the web UI;
- 8989/TCP – WSS protocol used by WebRTC to play the video;
- 8089/TCP – used by the web application to communicate with Janus server (REST API);
- */UDP – UDP is used for the RTP screencast (the port is chosen dynamically by Janus).
Notice: aPuppet requires enabling all incoming and outgoing UDP traffic, especially if you’re behind a NAT.
1. Clone the source code repository from GitHub.
git clone https://github.com/h-mdm/apuppet-server.git
Notice: the information written below can be also found in the file README.md in more details.
2. Configure the installer.
Open the file config.yaml in any text editor (vim or nano) and enter the domain name where you install aPuppet and your email address. The address is only used by LetsEncrypt to generate an SSL certificate.
3. Run the installer.
That’s all! After the successful run of this command, aPuppet will be configured, installed and started. Open the aPuppet domain name in a web browser to make sure it is up and running.
Notice the secret printed by the installation script. This secret must be configured in the Android application to avoid unauthorized remote access through your aPuppet server. If you forget the secret, you can find it in the file ./dist/credentials/janus_api_secret at any time.
4. Test the remote access.
Install the aPuppet mobile agent from Google Play (search for apuppet or use this direct link on a device: https://play.google.com/store/apps/details?id=com.hmdm.control.
At first start, the Android app will request you to grant permissions, and asks for the server URL and secret. Enter the URL in the form
and the secret generated by the installer script.
After setting up the Android app, you must see a green dot and the status must be “Connected”. Enter the session ID and PIN code in the aPuppet webpage and make sure the mobile device can be remotely controlled.
The system is based on docker-compose, therefore you need to use docker-compose commands to start, restart, stop, and other aPuppet management actions.
Before executing the management commands, change the current directory to the aPuppet directory:
docker-compose up --detach
More information is available in the README.md file.
Installing aPuppet behind a NAT
aPuppet can be installed behind a 1-to-1 NAT (for example, on AWS and Oracle clouds). To work behind a NAT, you need to add the following parameters to config.yaml:
Parameter public_ip is optional and needs to be set only if the aPuppet domain name is not resolved as a public IP address on the local host.
Installing aPuppet in LAN
aPuppet server is a self hosted remote access software and can be installed in a private network without Internet connection (LAN, VPN, private APN).
The system must be installed in the same way as for an Internet domain but there is a HTTPS-related trick. aPuppet Community uses LetsEncrypt as an SSL certificate provider, and it requires Internet connection to the host at least each 3 months (you cannot renew the certificate for a domain which is unavailable in Internet).
To avoid possible service interruptions due to frequent certificate renewals, use aPuppet Premium for LAN-based remote access service, and additionally purchase a commercial SSL certificate valid within maximal possible time (for example, 5 years).