Skip to content

02_macOSX.md

Latest commit

 

History

History
186 lines (127 loc) · 4.72 KB

02_macOSX.md

File metadata and controls

186 lines (127 loc) · 4.72 KB
Raw

Installing on macOS

Introduction

This guide details the installation process for the iR Engine on macOS devices.

Prerequisites

Ensure you have the following tools installed on your system before starting the installation:

Installation instructions

Follow these steps to set up the iR Engine on your macOS device.

Step 1: Prepare your project

First, generate a copy of the project by cloning the repository and navigate to the project directory:

::::workflow-block :::workflow-block-item Open your terminal :::

:::workflow-block-item Clone the repository by running:

git clone https://github.com/ir-engine/ir-engine.git

:::

:::workflow-block-item Navigate to the directory of the cloned repository by running:

cd ir-engine

::: ::::

Step 2: Set up environment variables

The iR Engine requires specific environment settings. Configure them by running:

cp .env.local.default .env.local

This command creates a copy of the default environment file, .env.local.default, renaming it to .env.local for use by the application.

Step 3: Install and activate the recommended Node.js version

The iR Engine functions with a specific Node.js version, outlined in the .nvmrc file. To activate the recommended version, run:

nvm use

Command output options:

  • If the version is found (✅): The system switches to the recommended Node.js version.
  • If the version is not found (❌): The system returns a message indicating the missing version.

To resolve, run the following commands:

::::workflow-block :::workflow-block-item Install the missing version:

nvm install <version>

:::

:::workflow-block-item Activate the version:

nvm use

::: ::::

Step 4: Install dependencies

Install the required dependencies by running:

npm install

Upon completion, proceed to initialize and run your development environment.

Run your development environment

This section contains the instructions to run your local development environment.

Step 1: Start Docker and initialize the database

::::workflow-block :::workflow-block-item Open Docker Desktop :::

:::workflow-block-item Initialize the database by running:

npm run dev-reinit

::: ::::

Step 2: Start the development environment

Launch the iR Engine development environment with:

npm run dev

:::hint{type="success"} This command opens the application at https://localhost:3000/location/default in your web browser. :::

Step 3: Open your development environment

Navigate to the application's URL in your browser to start working with the iR Engine development environment.

Step 4: Accept the certificates

When accessing the iR Engine for the first time, browsers block access due to self-signed certificates. This prevents you from accessing the Admin panel and the Editor. To bypass this, manually accept the certificates:

:::::workflow-block :::workflow-block-item Open developer tools

  • Chrome/Edge: Click the three-dot menu → More tools → Developer tools
  • Shortcut: Press Ctrl+Shift+I or F12
  • Navigate to the Console tab. :::

:::workflow-block-item Identify certificate-related errors

Check for network request errors related to:

  • WebSocket connections (wss:// URLs)
  • HTTPS requests to localhost

The following addresses require certificate approval:

  • https://localhost:3030 – API server
  • https://localhost:8642 – File server :::

::::workflow-block-item Bypass the security warning

  1. Open these URLs directly in your browser:
  2. https://localhost:3030
  3. https://localhost:8642
  4. A "Your connection is not private" warning appears.
  5. Click Advanced → Proceed to localhost (unsafe).
  6. Reload the engine’s website.

:::hint{type="info"} ** Why bypassing security warnings?** Browsers block connections to self-signed certificates by default to protect users from potentially unsafe sites.

For local development, it's safe to bypass these warnings, but only if you trust the source—like your own machine or your team's local environment. ::: :::: :::::

:::hint{type="success"} Once completed, the iR Engine’s admin panel and editor will be fully accessible. 🚀 :::

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