The goal of this article is to address some of the common pitfalls when setting up the Get a Room Appconnector and help troubleshoot these issues.
Table of contents
Appconnector Checklist
Each item on this list is an absolute requirement to run the Appconnector successfully.
- A Windows or Linux server that is reachable on a port (default is 8443) using a fully qualified domain name - using an IP address will not work. This server can be the same machine as your Evoko Home server. If installing the Appconnector on its own server, it needs to be able to connect to Evoko Home over the configured secure port (default 3002) using TCP.
- A certificate valid for the FQDN of the server, issued by a globally trusted CA. If you are using your own CA, you must include all certificates needed for the trust chain to be valid, which might mean root and intermediate certificates. Self-signed certificates will not work. Installing custom root certificates on the mobile devices via MDM will currently not help, but we are working on a fix for this.
- An SMTP server that the Appconnector can connect to and send emails.
Known issues
Node modules subfolder missing after install
This issue only affects some Windows installs.
After installing the Appconnector, make sure your appconnector program folder contains a node_modules subfolder:
If it does not, please download this zip file and unzip it in the Appconnector install folder. Make sure you don't get two levels of node_modules folders. The C:\Program Files (x86)\EVOKO\App Connector\node_modules folder should contain >250 items. If it contains just one node_modules folder you need to move the contents one folder level up. This issue is because the installer can not access https://www.npmjs.com/ during the install.
Common pitfalls
Service does not start
If the service does not start properly, make sure to stop it (not just pause it), then go to the Start menu -> Evoko App connector folder, and click the Open in foreground item. This will start the Appconnector in a Command Prompt window which will give some hints to what is going wrong during startup.
If the Evoko Appconnector service is running when starting the Open in foreground, this will cause an error message.
Error: Failed to start server, make sure port 8443 is available and that your SSL certificate settings are correct.
First, make sure that the Evoko Appconnector is not started as a service and is not running in the foreground. Then, open a Command Prompt window (or Terminal if on Linux) and enter:
netstat -a | findstr 8443
If you see an output, something else is listening on port 8443, which means the Appconnector can't use that port. Either find and stop the other service listening to port 8443 or change the Appconnector port in the config file:
# App Connector server port
port = 8443
If you did not get a result from the netstat command, the issue is most likely with the certificate. Move on to the "Certificates Verification" chapter.
Certificates Verification
Using OpenSSL, you can test your certificate and key in a number of different ways. In the examples below, we are assuming you are running the Appconnector and Evoko Home on the same Windows server and that the certificates are shared between Evoko Home and the Appconnector. If this is not the case in your environment, please adjust the paths accordingly.
If you do not have OpenSSL, you can download it for free from openssl.org. OpenSSL is also included in Evoko Home. To use it, open a Command Prompt or Terminal window and cd to the openssl subfolder in the Evoko Home install folder.
Please note that the Appconnector needs an unencrypted key file, so if you get a password prompt when entering the commands below, please go to "Decrypt the private key" and run that command.
View certificate entries:
openssl x509 -text -noout -in "C:\Program Files\EVOKO\EvokoHome\liso_files\certificates\server.crt"
Pay attention to the Issuer and Subject so they match what is needed.
Verify that the private key is valid:
openssl rsa -check -in "C:\Program Files\EVOKO\EvokoHome\liso_files\certificates\server.key"
Verify that the key and certificate match:
openssl rsa -noout -modulus -in "C:\Program Files\EVOKO\EvokoHome\liso_files\certificates\server.key" | openssl md5
openssl x509 -noout -modulus -in "C:\Program Files\EVOKO\EvokoHome\liso_files\certificates\server.crt" | openssl md5
If the checksum output is the same on both commands, the key and cert probably match.
Decrypt the private key:
Only needed if the private key is encrypted (password protected).
openssl rsa -in "C:\Program Files\EVOKO\EvokoHome\liso_files\certificates\server.key" -out "C:\Program Files\EVOKO\EvokoHome\liso_files\certificates\decrypted.key"
Remember to update the configuration to use the decrypted key.
If the Evoko Appconnector still will not start, please open a support ticket.