Provide more detailed instructions for running a local cloud-sync server

[kristianhentschelbbc]

Installing a cloud-sync server on a Ubuntu 22.04 virtual machine for local testing

I followed these steps to run a local cloud-sync server for use with Audio Orchestrator, instead of the instructions in the cloud-sync repository.

Note specifically that a service can be run without using the start_service.sh script, and without installing Node.JS and manually running the npm install or grunt steps suggested there (these will happen inside the controlled docker environment where they are less likely to fail)!

Prerequisites

I started with a virtual machine running Ubuntu 22.04 server, that can access the internet directly to install packages, and that I can log into using an SSH connection. This was an x86 host, some of the cloud-sync containers will not work on ARM (including the latest Apple computers).

Limitations

I did not attempt to configure SSL certificates to enable a wss:// connection. Note that this means other people could read the control messages sent between connected devices and is thus not suitable for a public deployment on the internet. I unfortunately cannot provide full instructions for running a public cloud-sync server.

I only tested this by using SSH tunneling to forward the cloud-sync ports to my development laptop; I cannot advise how to configure firewalls or make these ports available to other devices on a local or public network. This will depend on your virtual machine host.

Docker and docker-compose

The cloud-sync services run as Docker containers. Docker does not come pre-installed on Ubuntu.

I followed these instructions (steps 1 and 2 only) to install docker on my Ubuntu virtual machine: https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-22-04

I then added docker-compose following these instructions: https://docs.docker.com/compose/install/standalone/

Verify that docker and docker-compose run and return the default usage message.

Cloud-Sync

Get a copy of the cloud-sync repository and move into the directory:

git clone https://github.com/2-IMMERSE/cloud-sync.git && cd cloud-sync

Edit docker-compose.yml to insert the VM’s public IP address, with the ws:// protocol and the port number 6676 in the three places WALLCLOCK_SERVICE_WS_URL is defined:

WALLCLOCK_SERVICE_WS_URL:  ws://<your-public-ip>:6676

Start the containers and detach your terminal

docker-compose up -d

Later shut the services down again with docker-compose down if needed.

Cloud sync by default uses ports 9001 (mqtt service) and 6676 (wallclock service). You might have to forward these or allow access in firewall rules.

Errors / logs

Check the start up logs from the various containers:

docker-compose logs -f

• cloud-sync-consul-1 reports “no cluster leader” errors during startup, this is normal and later resolved once all services are ready.
• cloud-sync-synchronisedvideo-1 container fails to start up, cannot create some files. This one can be ignored, it is only for a test page.

Test cloud-sync

I didn’t try to expose the cloud sync ports on the VM firewall and instead forward them through an SSH tunnel (ssh -L 6676:localhost:6676 -L 9001:localhost:9001 ubuntu@<my-vm-ip-address>) after configuring cloud-sync to advertise the wallclock service as ws://localhost:6676.

In Audio Orchestrator, in the Export page Advanced Settings, configure the cloud-sync connection as:

• Cloud-Sync service hostname: <ip-of-your-vm> (or localhost if forwarding ports as I did)
• Port number: 9001

Starting a preview should now allow you to connect to your service.

Troubleshooting
If the preview application cannot connect to the synchronisation service:

• first double-check the Audio Orchestrator export settings match the public IP address and port number,
• then check the configuration in docker-compose.yml uses the ws:// protocol (not the default wss://) and includes the port number (:6676), and try restarting the containers (with docker-compose up).

You can check if the service is running by attempting to open the URLs in a browser (assuming you’ve forwarded ports as I have, or with the curl tool running on the VM itself):

• http://localhost:6676 should get a message like “Upgrade required” (indicating that it expects a WebSocket connection, not plain HTTP).
• http://localhost:9001 should get a message like “connection reset” or “empty reply” (whereas if the service is not accessible, it will be more like “unable to connect”)