How to deploy Joan on an on-premises server

To deploy Joan on your own server infrastructure, you will need to run a virtual machine on your server that will allow Joan to connect to the calendar solution you are using.

This virtual machine is based on Ubuntu 20.04 LTS x64 and uses the Visionect Software Suite software to provide connectivity to the devices. 

There are several steps in the deployment process:

  1. Make sure your infrastructure meets the system requirements
  2. Import the virtual machine
  3. Make sure you bind the network adapters properly
  4. Start the virtual machine and log in
  5. Access the server dashboard
  6. Connect your devices

System requirements

For information which virtual machine (VM) hypervisors are supported and the number of server resources required, please click here to learn more.

If you are using a 172.17.x.x/16 or 172.18.x.x/16 subnet, there is a probability of certain issues coming up, so we highly advise you to change the default docker and/or the docker-compose subnet.

Import the virtual machine

First, you will need to download the correct virtual machine based on the hypervisor that you are using:

For further instructions on how to use the virtual machine with each of the hypervisors can be found here:

If your hypervisor is not listed, try importing the virtual machine anyway, following the instructions for using OVF (open virtualization format) appliances. Our virtual machine is generic.

Make sure you bind the network adapters properly

The virtual machine comes with multiple network adapters.

The first is bound to the NAT interface and is used for access to the outside world (internet). The other should be bridged to one of your internal networks. The internal network should assign an IP using DHCP, preferably with a static DHCP lease. This IP needs to be accessible on port 11113 by your Joan devices.

You could also do port forwarding on NAT if you prefer – the only requirement is that the devices connect to the server on port 11113.

If a single network adapter can provide access to the internet and to the internal network, then the second one can be removed.

Start the virtual machine and log in

With network adapters properly bound, it is time to start the virtual machine. Simply follow these steps:

  1. Start the virtual machine
  2. Once started, you will be greeted with the following message
    • If the screen is blank, please press the “Enter” key. The virtual machine might be displaying a screensaver
  3. Log in using the default credentials (please note, we strongly advise changing the default server credentials due to security reasons. For more details please visit the link)
    • Username: joan
    • Password: joanaccess


If you change the default settings, password or networking configuration, please make sure that the virtual machine has access to the internet (so it can reach the Joan Portal for data about your calendars) and that Joan devices have access to the server.

Please find the instructions to change the VSS server IP settings here

Access the server dashboard

Once everything is deployed and configured properly, you will be able to manage your server via the VSS dashboard.

To do so, follow these steps:

  1. Go to the admin dashboard of your server
  2. Log in with your credentials. By default, the following credentials are set
    • Username: admin
    • Password: admin123

And once logged in, navigate and explore the dashboard. Good luck and happy hosting!

If you wish to change the login credentials, click here to learn how.

Connect your devices

Finally, it is time to connect your devices to the server. This can be done with the Joan Configurator tool.

Here’s how:

  1. Run the Joan Configurator
    • If you are using Windows or macOS, simply run the file
    • If you are using Linux, follow these steps:
      • Open the Terminal
      • Navigate to the destination folder where you downloaded the file. For example
        cd Downloads
      • Run the Joan Configurator as a superuser with the following command
        sudo ./JoanConfigurator_linux
  1. Connect the Joan device to your computer with the provided Micro USB cable
  2. Once connected, click the “Configure” button in the bottom-right corner of the window
  3. Click “More options
  4. Under the “JOAN HOSTING” section, select your “On-premises hosting
  5. Enter the IP address of your on-premises server
  6. Click “Save

And that’s it! Your device will connect to the server shortly after.