Skip to main content

Installation on Linux

Pre-Install Checklist​

  1. Ensure you have at least 16GB of RAM
    You may run int issues running the full development setup with less
  2. Clone the repository to a location whose path contains no spaces.
  3. Install Node.js 18
    (versions earlier than 16 are not guaranteed to work)
  4. Install Python >=3.6, PIP, C++, and other build tools
    See the Mediasoup install instructions for full details.
  5. Install Docker
    Optionally: If you're NOT using docker, install MariaDB, Redis and MinIO manually and update repo's .env.local accordingly.

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 everything, use this command:

git clone https://github.com/etherealengine/etherealengine --depth 1

Warning:
Adding --depth=1 will significantly reduce the amount of data downloaded when cloning, but it will also create a Shallow Copy of the engine's repository.
If you need to download any branch other than dev, or go back in git history into an older commit, you will have to unshallow the repository first, or else any branches and older commits won't be accessible. The command to undo cloning with --depth=N is either git fetch --unshallow or git pull --unshallow

Ensure you are running Node 18​

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

The best way to install and manage Node.js versions is by using a version manager:

  1. Install NVM
  2. Install Node.js 18 with nvm install 18
  3. (Optional) Make Node.js 18 your default node version with nvm alias default 18

Note: Polyglot ASDF can also be used for managing node versions.

Please check the output of node --version before running the engine.
If you are using a node version below 16, please update or nothing will work.
You will know that you are having issues if you try to install packages at root with npm install and you get package 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 /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 18, and check your dependencies.

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

Now run Ethereal Engine in your browser by navigating to this link.

Accept Certificates​

When loading the engine's website for the first time you'll have to tell your browser to ignore insecure connections.

  1. Open the Developer Tools of your browser by clicking the side menu with three dots, then go to More tools > Developer tools (or use either Ctrl+Shift+I or F12) and then go to the Console tab.
  2. You will see some errors in URL addresses starting with wss
    • Replace wss with https and open that URL in a new tab
    • Accept the certificate
    • Reload your Ethereal Engine's tab
  3. You will see some errors in URL addresses starting with https://localhost:9000
    • Open the URL linked in one of those errors
    • Accept the certificate
    • Reload your Ethereal Engine's tab

You need to do this for the following domains:

If the engine's website keeps displaying loading routes progress for a long time, it means that you have to allow the engine's certificates.

Web browsers will throw warnings when navigating to pages with unknown certificates (aka: insecure pages). You should be able to tell the browser to ignore these warnings by opening your browser's advanced options, but during development it is easier to just ignore the browser's warnings and accept the default certificates.

Note: You will be able to create signed certificates to replace the default ones when you deploy your own Ethereal Engine stack.

Admin System and User Setup​

You can administrate many features from the admin panel found at the /admin route of your deployment.
eg: https://localhost:3000/admin when working in a local deployment.

To give administration rights to a user:

  • Open any page in your Ethereal Engine deployment
  • Open the user menu (icon at the top-right of the screen)
  • Click on Show API key
  • Copy that key to your clipboard (note: there is an icon to the right of this box for this purpose)
  • Open a terminal and go to the folder where EtherealEngine was cloned.
  • Run the command npm run make-user-admin -- --id={COPIED_USER_ID} where COPIED_USER_ID is the key you just copied on the previous step.
    Example: npm run make-user-admin -- --id=c06b0210-453e-11ec-afc3-c57a57eeb1ac

image

Alternate Method:
Open the User table of your deployment's database and change userRole to admin
(It helps to use a graphical database explorer, we recommend beekeeperstudio.io) The location of the database can be found in your .env.local file.

Test user Admin privileges by going to the /admin route of your deployment.

Advanced Installation and Troubleshooting​

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