Skip to content
Ontime documentation

Headless Ontime

You can leverage the headless distributions to run Ontime in a computer without GUI.
This could be in a local machine part of the venue’s installation, a small Raspberry Pi or even a server running in the cloud.

Headless installs are the most lightweight and versatile ways to distribute and install Ontime.

Using NPM

Getting started

Prerequisites

You will need to have installed the correct version of node.js.
Please check the app engines declaration for the correct version.

Running Ontime

To get Ontime running, all you need to do is install it in your system using your package manager of choice:

Install globally in your system

Terminal window
npm install -g @getontime/cli

… and run using the installed script

Terminal window
ontime

Or install and run ontime (the installation here is temporary for the duration of the session)

Terminal window
npx install @getontime/cli

Once running, the app will be available in any device on the same network over (default port 4001)

Using Docker

Getting started

Install Docker on your machine.
Please refer to Docker or Raspberry Pi guides for this step

Once Docker is installed, pull the Ontime image from Dockerhub using the command:

Terminal window
docker pull getontime/ontime

You can find an example of docker-compose in the Docker repository to help you get started. 
To start ontime with the example docker compose file use the command:

Terminal window
docker-compose up -d

Notes on Docker-compose

Considering the example docker-compose below

version: "3"


services:
  ontime:
    container_name: ontime
    image: getontime/ontime:latest
    ports:
      - "4001:4001/tcp"
      - "8888:8888/udp"
      - "9999:9999/udp"
    volumes:
      - "./ontime-data:/data/"
    environment:
      - TZ=Asia/Singapore
    restart: unless-stopped
  • 4001:4001/tcp binds local port 4001 to the same container port. Port 4001 is the default for the UI and is necessary to expose the app.
  • 8888:8888/udp binds the localhost port 8888 (default for OSC input into the app) to the same in the container, so that it can receive data from the host machine targeted to the loopback interface.
  • 8888:8888/udp binds the localhost port 9999 (default for OSC output from the app) to the same in the container, this allows Ontime to send data out of the container.
  • "./ontime-data:/data/" expose the internal container data directory.
  • TZ=Asia/Singapore overrides the container timezone.

The variations in the network setup will widely depend on your setup.

Common questions 🚨

Ontime default port

Ontime serves its web pages on port 4001.  In the docker compose example 4001:4001/tcp exposes this port to the outside so it can be accessed at http://<ip-address>:4001. Instead, you could use 80:4001/tcp to expose the internal container port 4001 to the outside port 80 (the default for http). That means your URLs would be slightly simpler since you wouldnt need to provide a port, (eg: http://<ip-address>/editor instead og http://<ip-address>:4001/editor)

Volumes

The app interacts with some directories that the user can interact with. In a docker instance, we need to expose this manually to the container host. Namely:

  • /data/projects/ contains all of Ontime’s project files
  • /data/styles/ contains the user provided CSS Override
  • /data/external/ is a placeholder directory that users can ues to distribute data through Ontime

You can bind a single host directory to /data/ for Ontime to store all its files in (as in the example docker-compose, above), or expose the individual parts to host directories:

    volumes:
      - "./ontime-projects:/data/projects/"
      - "./ontime-styles:/data/styles/"
      - "./ontime-external:/data/external/"

Setting the time in the container

Docker containers default to UTC timezone, which you can modify using the TZ environment variable.

Setting time in a Docker container is not an operation specific to Ontime.
See as an example the instruction in the following blog post, which also contains a list of timezones to use in Docker.

I can see the UI but no timers will start

Ontime uses WebSockets to transport the time data from the server to the UI.
It can be the case that you are leveraging the Docker image to run Ontime in a cloud server or a server behind a reverse proxy.

In those cases, it is common that the WebSocket transport needs some additional configuration in the server side.
See documentation for NGINX and this example guide for Synology.