Skip to main content


Getting up and running requires just a few steps, but this can be tricky, depending on your platform and current environment. Please follow the directions for your environment.

Pre-Install Checklist

  • Clone the repository
  • Install Node.js v16 (later versions not guaranteed to work)
  • Install Python >=3.6 + PIP, C++, and other build tools. See the Mediasoup install instructions for full details.
  • Install Docker (optional but highly recommended)
  • (Optional) If you're NOT using docker, install MariaDB and Redis.

You should now be ready to follow the Quick Start instructions.

Clone the repository

A lot has changed during development, and our monorepo has gotten quite large. To avoid cloning the entire thing, use this command:

git clone --depth 1

Ensure you are running Node 16

The engine to date has only been confirmed to work perfectly with Node 16.x. Earlier or later major versions are not guaranteed to work properly.

A version manager can be helpful for this:

(Note: As of this writing, June 15 2022, the implementation of PhysX that's used in the engine package does not work properly with Node versions 18.1 and higher, due to Node's implementation of WebAssembly making PhysX think that it's running in the browser. We are in the process of replacing PhysX with Rapier; when that is done, it should work with Node >= 18.1)

Before running the engine, please check node --version If you are using a node version below 16, please update or nothing will work. You will know you are having issues if you try to install at root and are getting dependency errors.

Docker is your friend

You don't need to use Docker, but it will make your life much easier. If you don't wish to use Docker, you will need to setup mariadb and redis on your machine. You can find credentials in ethereal-engine/scripts/docker-compose.yml

Quick Start

If you are lucky, this will just work. However, you may encounter some issues. Make sure you are running Node 16, and check your dependencies.

cd path/to/ethereal-engine
cp .env.local.default .env.local
npm install
npm run dev-docker
npm run dev-reinit
npm run dev

Setup Elastic Search & Grafana

Elastic Search and Grafana will be automatically launched with npm run dev.

Elasticsearch & Grafana will be running on localhost port 9200 & 5601 respectively.

This will automatically set up and run Redis/MariaDB docker containers, and Ethereal Engine client/server/instance-server instances.

In a browser, navigate to

The database seeding process creates a test empty location called 'test'. It can be navigated to by going to ''

As of this writing, the cert provided in the ethereal-engine package for local use is not adequately signed. Browsers will throw up warnings about going to insecure pages. You should be able to tell the browser to ignore it, usually by clicking on some sort of 'advanced options' button or link and then something along the lines of 'go there anyway'.

Chrome sometimes does not show a clickable option on the warning. If so, just type badidea or thisisunsafe when on that page. You don't enter that into the address bar or into a text box, Chrome is just passively listening for those commands.

Admin System and User Setup

You can administrate many features from the admin panel at https://localhost:3000/admin

How to make a user an admin:

Create a user at https://localhost:3000/

To locate your User ID: In Chrome Dev Tools console, write copy(userId). This will copy your User ID (As shown in attached screenshot). Paste it in and run the following command in a 'nix shell (e.g. Bash, ZSH):

npm run make-user-admin -- --id={COPIED_USER_ID}

Example: npm run make-user-admin -- --id=c06b0210-453e-11ec-afc3-c57a57eeb1ac


  1. TODO: Improve with email/phone ID support

Alternate Method:

  1. Look up in User table and change userRole to 'admin'
  2. Dev DB credentials can be found here: packages/ops/docker-compose-local.yml#L42
  3. Suggested:

Test user Admin privileges by going to /admin

Advanced Installation and Troubleshooting

If you run into any trouble with the Quick Start instructions: