Once you understand how the Theatersoft platform configuration works you’ll realize its full customization potential.

In essence, a config.json file describes the configuration state for the installation. It consists of general configuration options, the hosts list of one or more Theatersoft servers in your site, and a services list of service configurations for each server. Each service configuration contains a module name for the corresponding npm package name and a config object for custom service options.

Administration scripts automate the process of converting the configuration into a deployed server installation(s). The config script stages a generated package.json file for each server containing that servers service module dependencies. The deploy script copies the generated packages to each server and performs the npm install package installation.

At runtime, the root server loads config.json and creates a Config bus service with APIs that makes the service configuration available to each server to use to start their services.

Initial Configuration

The @theatersoft/home package automates installation and configuration. It was installed and used during installation:

cd && mkdir example && cd example # replace example with your site/domain name
npm install @theatersoft/home
npm explore @theatersoft/home npm run config deploy

When you run npm run config deploy for the first time, it populates your site directory ~/example:

 ├── config.json
 ├── deploy
 ├── .gitignore
 ├── node_modules
 ├── package.json
 └── package-lock.json

Your site configuration file config.json was generated from a template. You can modify it with any text editor. Always use valid JSON syntax, even if documentation refers to properties as JavaScript objects (e.g. config.hosts).

  "_letsencrypt": {
    "domain": "",
    "email": "[email protected]",
    "production": true
  "password": "0000",
  "hosts": [
      "name": "raspberrypi",
      "host": "raspberrypi.local",
      "mac": "00:00:00:00:00:0",
      "services": [
          "enabled": true,
          "module": "@theatersoft/device",
          "export": "Device",
          "name": "Device",
          "config": {
  "configs": {

package.json contains administration scripts for config and deploy:

  "description": "Theatersoft Home site installation",
  "private": true,
  "scripts": {
    "config": "npm explore @theatersoft/home -- npm run config",
    "deploy": "npm explore @theatersoft/home -- npm run deploy",
    "deploy-raspberrypi": "npm run deploy -- -- -- raspberrypi",
    "journal-raspberrypi": "journalctl -u theatersoft -f --no-tail",
    "restart-raspberrypi": "systemctl restart theatersoft",
    "stop-office": "systemctl stop theatersoft"
  "dependencies": {
    "@theatersoft/home": "~2"
  "theatersoft": {
    "pack": false,
    "port": 443
  "name": "example"

The deployment files for each host are staged in deploy:

└── raspberrypi
    ├── .bus
    ├── package.json
    ├── .root
    └── theatersoft.service

Adding Services

Available services are listed in Services. Check the documentation first to find any specific installation instructions such as hardware requirements.

There are two basic steps to add a service:

  1. Copy the sample configuration object and paste it into config.json by adding it to a[] array, making any customizations as instructed.

  2. Rerun npm run config deploy

Adding Servers

You can also add additional servers. For example, you may need to connect device controllers or video capture cards to machines in separate locations.

The steps to add a server are similar to adding individual services:

  1. Edit config.json and add a new entry to the host[] array, using an existing host as a template and setting name, host, and services as needed.

  2. Rerun npm run config deploy (This requires passwordless login to the host using ssh key authentication.)