# Installation - on-premise

# OmniMES installation

The complete OmniMES deployment procedure - from downloading Docker, through license activation, Redash and the Ollama AI server configuration, to changing passwords, updating and uninstalling.


---

## 1. Prerequisites

Before installation, make sure the following **ports are free** on the target computer:

| Port | Service |
|------|---------|
| 80   | Web interface (frontend) |
| 8091 | Backend API |
| 5000 | Redash (reports) |
| 1883 | MQTT broker (TCP) |
| 1884 | MQTT broker (WebSocket) |
| 8083 | EMQX - broker administration panel |

**Docker** is also required: <https://docs.docker.com/get-docker/>


:::info
The recommended environment for a production server is **Linux (Debian / Ubuntu Server LTS) with Docker Engine**. Docker Desktop for Windows is suitable for testing and demonstrations - why we do not recommend Windows Server is explained in the *Hardware requirements* chapter and in section 10.4.

:::


---

## 2. Step-by-step installation


1. Download and install the Docker version appropriate for your system.
2. From the installation package, run the script matching your operating system:
   * **Windows:** `install_all_windows.bat`
   * **Linux:** `install_all_linux.sh`

   These scripts install the **full version of OmniMES** together with the components: API, Stream, WWW, Redash and Ollama.
3. **Linux - granting permissions** (before the first run):

   ```bash
   chmod +x install_linux.sh uninstall.sh updated_api.sh updated_www.sh
   ./install_all_linux.sh
   ```
4. **Windows - the "Windows protected your PC" message** Click **More info** → **Run anyway**.


---

## 3. First login

### 3.1. Opening the application in a browser

After the script finishes, open a browser and type one of the following addresses into the **address bar**:

* `localhost`
* `127.0.0.1`
* the local IP address of the computer where the software was installed

The OmniMES login screen will appear.

### 3.2. Filling in the login screen

The login form has **three fields** - fill them in as follows:

| Field | What to enter | Notes |
|-------|---------------|-------|
| **API URL** | the OmniMES backend address, e.g. `http://localhost:8091` | This is **not** the browser address - it is the address of the API service, which always runs on port **8091**. If OmniMES runs on another computer, replace `localhost` with its IP, e.g. `http://192.168.3.100:8091`. |
| **Username** | `omni`        | The default account created after installation. |
| **Password** | `#omni2026`   | The default factory password. |

> ℹ️ **Common mistake:** in the **API URL** field you enter the address of the backend service (port `8091`), **not** the address from which you open the browser (port `80`). These addresses usually differ by port and may point to different hosts (e.g. the frontend locally, the API on a server).

> ⚠️ **Security:** The factory password should be changed **immediately after the first login**.


---

## 4. License activation

After logging in, the system automatically takes you to the activation screen. Enter the **license key** provided with the package - the product is ready to use.


---

## 5. Redash configuration (reports)

Redash is the built-in OmniMES reporting engine, available locally at:

```
http://localhost:5000/
```

> ℹ️ After installation the **Redash database is restored automatically** - together with a ready-made data source, queries and dashboards. **There is no need to manually add a JSON data source or configure the connection.** Just follow the three steps below.

### 5.1. Log in to Redash

Open `http://localhost:5000/` and log in with the default credentials:

| Field | Default value |
|-------|---------------|
| **Email** | `omni@omnimes.com` |
| **Password** | `#omni2026`   |

### 5.2. Change the default login and password

For security reasons **change the default email and password immediately**: in Redash click **Settings** (bottom-left corner) → **Account** and set your own credentials.

### 5.3. Generate a token and paste it into OmniMES


1. In Redash go to **Settings → Account**.
2. In the **API Key** section click **Regenerate** to generate a **new token**, then copy it.
3. In OmniMES go to **Settings → Redash** and fill in:
   * **Redash address:** `localhost:5000`
   * **API Key:** the freshly generated token you copied

 ![](https://docs.omnimes.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzRlMDdmZmNhLThmZjAtNDYxYy1iYjEyLTA2OTEyZGRiOGQzNi85OWQwMjM3NS1hOTdlLTQ3OTgtYTdjMi05YTU0Yjk1NTU5NDUvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTQ0OTQ3MDAsImV4cCI6MTc5NDU4MTEwMH0.SVw_aFeauCBbXdnf9OLazBKaoBsymiLi7Uq06YqqLDE " =612.5x435.5")

From now on OmniMES is connected to Redash - you can use the ready-made reports and dashboards.


---

## 6. Ollama configuration (AI assistant)

The **Ollama** server provides local language models for the built-in AI assistant in OmniMES. It is **installed automatically** together with the full version of the system (the `install_all_*` scripts).

### 6.1. Hardware requirements

The default installation uses the **CPU**, so performance depends on the processor's power:

* **CPU (minimum):** a **24-core** desktop processor or stronger.
* **GPU (recommended):** an NVIDIA **3070** series card or higher (one or more, depending on the chosen AI model).

> 💡 **Recommendation:** For larger deployments, run Ollama **on a separate server** (Docker or natively).

### 6.2. Installation on a separate server

* Docker image: <https://hub.docker.com/r/ollama/ollama>
* Linux: <https://github.com/ollama/ollama/blob/main/docs/linux.md>
* Windows: <https://github.com/ollama/ollama/blob/main/docs/windows.md>

#### docker-compose.yaml

```yaml
version: '3.8'

services:
  ollama:
    image: ollama/ollama
    environment:
      - OLLAMA_ORIGINS="*"
      - OLLAMA_HOST="0.0.0.0:11434"
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama:/root/.ollama
    restart: unless-stopped

volumes:
  ollama:
```

For external access: `host = 0.0.0.0`, `port = 11434`, `CORS = "*"` (or narrowed down as needed).

### 6.3. Downloading an AI model

List of supported models: <https://ollama.com/library>

Downloading the chosen model:

```bash
ollama pull llama3
```

### 6.4. Linking with OmniMES

In OmniMES **Settings**:


1. Select the AI type: **internal**.
2. Enter the Ollama server address (e.g. `http://192.168.3.100:11434`).
3. The **AI model version** field should show the list of downloaded models.

If the connection fails, an error message appears in the field - check the server address and the open ports.


---

## 7. Changing system passwords

The **PostgreSQL database** or **MQTT broker** password is changed with the included `**set_pass.py**` script. The script operates on the running containers (`docker compose exec database psql`), so the **OmniMES stack must be running**, and the script itself only requires an installed **Python** and a working Docker - **no extra libraries** (no host, port, or old password needed). Run it in the directory containing the OmniMES stack `docker-compose.yaml`.

### 7.1. Changing the MQTT broker password (user `emqx`)

```bash
# Windows
py set_pass.py --newpassbroker NEW_BROKER_PASSWORD
# Linux / macOS
python3 set_pass.py --newpassbroker NEW_BROKER_PASSWORD
```

The script updates the MQTT `emqx` user password in the database, the stream `.env` file, and restarts the `stream` service.

### 7.2. Changing the PostgreSQL database password (user `omni`)

```bash
# Windows
py set_pass.py --newpassdb NEW_DATABASE_PASSWORD
# Linux / macOS
python3 set_pass.py --newpassdb NEW_DATABASE_PASSWORD
```

The script changes the `omni` user password, updates `omnimes/.env`, the EMQX auth configuration (`emqx_auth_pgsql.conf`), the API `config.json` and the stream `.env`, then restarts the `broker`, `api` and `stream` services - **nothing has to be done manually**.


---

## 8. System update

Each main component can be updated **independently** using dedicated scripts:

| Component | Windows | Linux |
|-----------|---------|-------|
| API       | `updated_api.bat` | `updated_api.sh` |
| Stream (MQTT / Sparkplug B) | `updated_stream.bat` | `updated_stream.sh` |
| Frontend WWW | `updated_www.bat` | `updated_www.sh` |

Each script performs the sequence: **pull → rebuild → restart the container**.

> 💡 **Linux:** remember the permissions - `chmod +x updated_*.sh` before the first run.

### 8.1. Full environment rebuild

In case of problems (a damaged container, configuration inconsistency) you can force a rebuild:

* **OmniMES:** `recreated_omnimes.bat` (Windows)
* **Redash:** `recreated_redash.bat` (Windows)

> ⚠️ The rebuild **does not remove the** `postgres_data` **volume** with the database data, but a backup is recommended before running it.


---

## 9. Uninstalling

### 9.1. Procedure

In the installation folder, run the script:

* **Windows:** `uninstall.bat`
* **Linux / macOS:** `uninstall.sh`

On Linux, remember to grant permissions first:

```bash
chmod +x uninstall.sh
./uninstall.sh
```

### 9.2. Warning - data loss

> ⚠️ Uninstalling removes **all containers, including the** `**database**` **container** (PostgreSQL + TimescaleDB), which stores the data from the production devices.
>
> **Before uninstalling, back up the database** - via **Adminer** (`http://localhost:8079`) or with `docker compose exec database pg_dump -U omni -Fc -d data > data.dump` (similarly for the `omni` database). Restore: `pg_restore`.


---

## 10. Exposing OmniMES outside the computer

### 10.1. What to do when port 80 is busy?

By default the OmniMES web interface runs on port 80. If the port is busy:

* **Option A:** free port 80 in the operating system (stop the service that uses it).
* **Option B:** change the port mapping in `docker-compose.yaml` - in the `www` section change the **left** number from `80:80` to e.g. `8080:80`. After this, OmniMES will be available at `http://<address>:8080`.

### 10.2. Exposing outside the local network

The configuration must be done **on the router**, directing traffic to the IP address of the computer where the system is installed. The required port forwarding:

| Port(s) | Service |
|---------|---------|
| 80, 443 | Web server |
| 1883, 1884 | MQTT - external devices sending data to the broker |
| 8083    | WebSocket Secure (WSS) - the data stream for preview in monitoring |

### 10.3. Connecting an external device (HMI / gateway)

On the device (HMI panel, communication gateway, etc.) specify:

* the OmniMES **server address**, e.g. `192.168.3.100`
* the **MQTT port:** `1883` (standard)
* the **EMQX broker login data:**
  * Login: `emqx`
  * Password: `Fb7jCkux` *(factory - change it after deployment, see section 7)*

### 10.4. Windows as a server (not recommended) - automatic Docker startup


:::warning
We recommend running OmniMES on a **Linux server with Docker Engine** (see the *Hardware requirements* chapter). On Windows Server, Docker Desktop is not supported by its vendor, and the Linux containers run inside an additional virtual machine. An installation on Windows Server requires individual arrangements with the OmniMES team.

:::

If the system has to run on Windows anyway, enable the **"Start Docker Desktop when you log in"** option in Docker Desktop. Keep in mind that Docker Desktop runs in the session of a logged-in user - after a restart (e.g. after Windows updates) OmniMES starts only once a user logs in.


---

## 11. Installation files - reference

### 11.1. Full installation

| File | Description |
|------|-------------|
| `install_all_linux.sh` | The full OmniMES system on Linux (API + Stream + WWW + Redash + Ollama) |
| `install_all_windows.bat` | The full OmniMES system on Windows (API + Stream + WWW + Redash + Ollama) |
| `install_all_without_ollama.bat` | Full installation **without Ollama** - Windows (faster, without LLM models) |
| `install_all_without_ollama.sh` | Full installation **without Ollama** - Linux |

### 11.2. Modular installation

| File | Description |
|------|-------------|
| `install_omnimes.bat` | Only the OmniMES base (API + Stream + WWW) - Windows |
| `install_omnimes_linux_mac.sh` | Only the OmniMES base - Linux / macOS |
| `install_ollama.bat` | Only the Ollama server - Windows |
| `install_ollama.sh` | Only the Ollama server - Linux |

### 11.3. Single-component updates

| File | Description |
|------|-------------|
| `updated_api.bat` / `updated_api.sh` | Update of the API container (pull → rebuild → restart) |
| `updated_stream.bat` / `updated_stream.sh` | Update of the Stream module (MQTT / Sparkplug B) |
| `updated_www.bat` / `updated_www.sh` | Update of the WWW frontend |

### 11.4. Environment rebuild

| File | Description |
|------|-------------|
| `recreated_omnimes.bat` | Rebuild of OmniMES - removes the containers and recreates them (Windows) |
| `recreated_redash.bat` | Rebuild of the Redash environment |

### 11.5. Uninstalling

| File | Description |
|------|-------------|
| `uninstall_all.bat` / `uninstall_all.sh` | Full removal of OmniMES (together with the data!) |
| `uninstall_omnimes.bat` / `uninstall_omnimes.sh` | Removes only the base OmniMES installation (without Redash, without Ollama) |
| `uninstall_ollama.bat` / `uninstall_ollama.sh` | Removes only Ollama |

### 11.6. Tools

| File | Description |
|------|-------------|
| `set_pass.py` | Python script - changes the PostgreSQL database (`omni`) and MQTT broker (`emqx`) passwords. Requires only Python and a running Docker (the stack must be up). |


---

## 12. `.env` configuration files

The installation package contains **two** `**.env**` **files** that configure the system. Set them **before the first run** of the installation script.

### 12.1. `omnimes/.env` - OmniMES stack

| Variable | Meaning |
|----------|---------|
| `POSTGRES_USER` | database superuser (default `omni`) |
| `POSTGRES_PASSWORD` | database superuser password (change in production) |
| `POSTGRES_HOST` | database host as seen from containers - `database` (service name) |
| `POSTGRES_PORT` | database port - `5432` |
| `OMNIMES_API_HOST` | **public** API address as seen from the browser, e.g. `http://192.168.1.100:8091` or `https://api.domain.com` |
| `OMNIMES_WWW_PORT` | WWW frontend port (default `80`) |

### 12.2. `redash/.env` - Redash stack

| Variable | Meaning |
|----------|---------|
| `REDASH_COOKIE_SECRET`, `REDASH_SECRET_KEY`, `COOKIE_SECRET`, `SECRET_KEY` | session/encryption secrets - **change in production** |
| `REDIS_URL` | Redis connection (`redis://redis:6379/0`) |
| `REDASH_DATABASE_URL` | connection to the `redash` database in the `database` container (`postgresql://omni:PASSWORD@database:5432/redash`) |
| `REDASH_HOST` | (optional) public Redash address - used to build links to public dashboards |
| `REDASH_MAIL_*` | (optional) SMTP mail server configuration - see the note below |

> ✉️ **Redash SMTP mail - set it BEFORE installation (if needed).** The `REDASH_MAIL_SERVER` / `REDASH_MAIL_PORT` / `REDASH_MAIL_USE_TLS` / `REDASH_MAIL_USE_SSL` / `REDASH_MAIL_USERNAME` / `REDASH_MAIL_PASSWORD` / `REDASH_MAIL_DEFAULT_SENDER` fields are needed **only** for **email alert notifications**, user invitations and password reset. Redash works without them.
>
> * If you want emails → fill these fields with **your own SMTP server before installation**.
> * If you do **not** use email → these lines **must stay commented out**. **Never leave an empty line** like `REDASH_MAIL_PORT=` - Redash runs `int('')` and the container goes into a **restart loop**.
> * After editing `.env`, **recreate the container** (`docker compose up -d`), not just `restart` - Docker Compose reads `.env` when **creating** the container, not on restart.


---

## 13. Moving data to another server (database dumps)

The system can be moved **with its data** to another server. On the old server, create dumps from the `database` container, copy them to `omnimes/database/base/` **before the build**, and the installation script will restore everything on the new server.

```bash
docker compose exec database pg_dump -U omni -Fc -d omni        > omni.dump        # configuration
docker compose exec database pg_dump -U omni -Fc -d omni_queue  > omni_queue.dump  # Django Q queue
docker compose exec database pg_dump -U omni -Fc -d mqtt        > mqtt.dump        # EMQX auth
docker compose exec database pg_dump -U omni -Fc -d redash      > redash.dump      # dashboards/queries/users
docker compose exec database pg_dump -U omni -Fc -d data        > data.dump        # telemetry (Timescale hypertable)
```

Copy the selected files to `instalka3/omnimes/database/base/` and run the installation.

| File (optional) | What it restores |
|-----------------|------------------|
| `omni.dump`     | configuration - in practice the only one needed (admin + menu to log in) |
| `omni_queue.dump`, `mqtt.dump`, `redash.dump` | queue / broker auth / Redash (transplant) |
| `data.dump`     | telemetry - **must** be `pg_dump -Fc` format (Timescale hypertable; Adminer/SQL cannot restore it) |

> ℹ️ No dumps = a fresh install: the schema is created by `migrate`, and the `data` database is fed by `stream`. Details and accepted formats (`.dump` / `.sql` / `.sql.gz`) are described in `database/base/README.md`.

---

**Documents**

- [OmniPlatform](https://docs.omnimes.com/s/cb8b19e0-ec6d-4e1a-8690-b0ddd67ad1cd/doc/omniplatform-7z9SIECi68)
- [Omnienergy](https://docs.omnimes.com/s/cb8b19e0-ec6d-4e1a-8690-b0ddd67ad1cd/doc/omnienergy-56aRDgnYFZ)
- [Omnimes](https://docs.omnimes.com/s/cb8b19e0-ec6d-4e1a-8690-b0ddd67ad1cd/doc/omnimes-eGDa0U5cyr)
- [FAQ](https://docs.omnimes.com/s/cb8b19e0-ec6d-4e1a-8690-b0ddd67ad1cd/doc/faq-IFQjCNYt1Q)
- [Cybersecurity & Compliance (CRA)](https://docs.omnimes.com/s/cb8b19e0-ec6d-4e1a-8690-b0ddd67ad1cd/doc/cybersecurity-compliance-cra-pPJBcC6sBf)