Debian 12

Section 1

System Prep

Before installing any service, update the package repositories and install the tools mo-installer and moctl depend on. Debian uses apt like Ubuntu but ships fewer packages by default.

1.1 Update the system

sudo apt update && sudo apt upgrade -y
sudo reboot

1.2 Install required utilities

sudo apt install -y \
  unzip wget curl jq net-tools vim bash-completion \
  ca-certificates gnupg lsb-release \
  lsof telnet sudo

1.3 Configure the firewall

Debian does not install ufw by default. Install it before configuring.

sudo apt install -y ufw
sudo systemctl enable --now ufw

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh

sudo ufw allow 8080/tcp comment 'miniorange'
sudo ufw allow 8070/tcp comment 'eurekaserver'
sudo ufw allow 8071/tcp comment 'configserver'
sudo ufw allow 8072/tcp comment 'gatekeeper'
sudo ufw allow 6379/tcp comment 'redis'
sudo ufw allow 5672/tcp comment 'rabbitmq-amqp'
sudo ufw allow 15672/tcp comment 'rabbitmq-mgmt'

sudo ufw --force enable
sudo ufw status verbose

1.4 AppArmor

Debian ships AppArmor but with fewer enforcing profiles than Ubuntu by default. No relaxation is required for the IDP.

sudo apt install -y apparmor apparmor-utils
sudo aa-status | head -5

Section 2

Database

PostgreSQL 16 on Debian 12 (bookworm). Ubuntu’s universe ships PostgreSQL 14, which is too old; add the official PGDG apt repository to get 16. The installer ships the PostgreSQL JDBC driver, so no manual driver placement is needed.

2.1 Add the PGDG apt repository

sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc \
  -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc

echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] \
  https://apt.postgresql.org/pub/repos/apt bookworm-pgdg main" | \
  sudo tee /etc/apt/sources.list.d/pgdg.list

sudo apt update

2.2 Install PostgreSQL 16

sudo apt install -y postgresql-16 postgresql-client-16 postgresql-contrib-16

2.3 Start the service

The Debian/Ubuntu PostgreSQL packaging initialises a cluster automatically on install.

sudo systemctl enable --now postgresql
sudo systemctl status postgresql@16-main

2.4 Create the miniOrange database and user

sudo -u postgres psql <<'SQL'
CREATE USER moadmin WITH PASSWORD 'Password123';
CREATE DATABASE miniorangedb OWNER moadmin;
ALTER USER moadmin WITH SUPERUSER;
SQL

2.5 Switch authentication to md5

sudo sed -i \
  -E 's/^(host\s+all\s+all\s+(127\.0\.0\.1\/32|::1\/128)\s+)(peer|ident|scram-sha-256)/\1md5/' \
  /etc/postgresql/16/main/pg_hba.conf

sudo systemctl restart postgresql@16-main

Note. Ubuntu’s PostgreSQL config lives in /etc/postgresql/16/main/ (not /var/lib/pgsql/16/data/ as on RHEL). The data directory is /var/lib/postgresql/16/main/.

2.6 Open the PostgreSQL port (only if remote access is needed)

sudo ufw allow 5432/tcp comment 'postgres'

2.7 Verify

PGPASSWORD=Password123 psql -h 127.0.0.1 -U moadmin -d miniorangedb -c '\l'

Values for the `/initialize` wizard

Field	Value
Database Type	PostgreSQL
Host	`127.0.0.1`
Port	`5432`
Database name	`miniorangedb`
Username	`moadmin`
Password	`Password123`

⚠ Derived, needs review. These steps are derived from the MySQL vendor's official install docs combined with the miniOrange PostgreSQL and Oracle source flow. They should work, but each command should be sanity-checked on this exact OS before production use.

MySQL 8.4 LTS on Debian 12. These steps are derived from the MySQL APT repo install path combined with the JDBC driver placement convention from the source Oracle flow; review before production.

2.1 Add the MySQL APT repository

Download the configurator and select MySQL 8.4 LTS for the server when prompted.

cd /tmp
sudo curl -L -O https://dev.mysql.com/get/mysql-apt-config_0.8.32-1_all.deb
sudo dpkg -i mysql-apt-config_0.8.32-1_all.deb
sudo apt update

The configurator writes /etc/apt/sources.list.d/mysql.list. Verify it points to the mysql-8.4-lts channel:

grep -E 'mysql-8\.4-lts' /etc/apt/sources.list.d/mysql.list

2.2 Install MySQL 8.4

sudo apt install -y mysql-community-server mysql-community-client

You will be prompted for the root password during install. Set a strong password and remember it; unlike RHEL, Ubuntu’s MySQL package does not generate a temporary one in the log.

2.3 Start and enable the service

sudo systemctl enable --now mysql
sudo systemctl status mysql

2.4 Secure the installation (optional but recommended)

sudo mysql_secure_installation

2.5 Create the miniOrange database and user

mysql -u root -p <<'SQL'
CREATE DATABASE miniorangedb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'moadmin'@'localhost' IDENTIFIED BY 'Password123';
CREATE USER 'moadmin'@'%'         IDENTIFIED BY 'Password123';
GRANT ALL PRIVILEGES ON miniorangedb.* TO 'moadmin'@'localhost';
GRANT ALL PRIVILEGES ON miniorangedb.* TO 'moadmin'@'%';
FLUSH PRIVILEGES;
SQL

2.6 Place the MySQL JDBC driver (derived assumption)

sudo mkdir -p /opt/miniorange/drivers
cd /tmp
sudo wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j_8.4.0-1debian12_all.deb
sudo dpkg -i mysql-connector-j_8.4.0-1debian12_all.deb
sudo cp /usr/share/java/mysql-connector-j-8.4.0.jar /opt/miniorange/drivers/
sudo chmod 644 /opt/miniorange/drivers/mysql-connector-j-8.4.0.jar

2.7 Open the MySQL port (only if remote access is needed)

sudo ufw allow 3306/tcp comment 'mysql'

2.8 Verify

mysql -u moadmin -pPassword123 -h 127.0.0.1 -e 'SHOW DATABASES;'

Values for the `/initialize` wizard

Field	Value
Database Type	MySQL
Host	`127.0.0.1`
Port	`3306`
Database name	`miniorangedb`
Username	`moadmin`
Password	`Password123`

✕ Not supported. Microsoft does not publish a Debian repo

Microsoft does not publish an MSSQL apt repository for Debian. The Debian community has never been on Microsoft’s supported Linux matrix for MSSQL on Linux; only Ubuntu, RHEL, and SLES are listed.

What this means

A single-host miniOrange + MSSQL deployment is not possible on Debian 12. Two viable workarounds:

Use a different OS for the IDP. Ubuntu 22.04 is the closest behavioural match to Debian 12; if MSSQL is a hard requirement, switching the IDP host to Ubuntu 22.04 keeps your apt-based ops workflow intact and unlocks the supported MSSQL path.
Run MSSQL on a separate host. Install MSSQL on RHEL, SLES, or Ubuntu, then on this Debian 12 IDP host place only the JDBC driver and point the wizard at the remote DB.

JDBC-driver-only path on Debian 12

If you go with option 2:

sudo mkdir -p /opt/miniorange/drivers
cd /tmp
sudo curl -L -o mssql-jdbc.tar.gz \
  https://download.microsoft.com/download/8/c/d/8cdfd87a-1684-4731-91a9-2ba182c8b0ad/sqljdbc_12.6.4.0_enu.tar.gz
sudo tar -xzf mssql-jdbc.tar.gz
sudo cp sqljdbc_12.6/enu/jars/mssql-jdbc-12.6.4.jre11.jar /opt/miniorange/drivers/
sudo chmod 644 /opt/miniorange/drivers/mssql-jdbc-12.6.4.jre11.jar

Values for the `/initialize` wizard (remote MSSQL host)

Field	Value
Database Type	MSSQL
Host	`<mssql-host>` (remote DB IP)
Port	`1433`
Database name	`miniorangedb`
Username	`moadmin`
Password	`Password123!`

◐ Partial support. Instant Client only on Debian

Partial support. Oracle does not ship Oracle Database 19c for Debian or Ubuntu. The native install path used on Oracle Linux 8 and RHEL 9 (preinstall RPM, server RPM, sqlplus, listener auto-config) is not available here. The supported pattern for Oracle on Ubuntu is: run the Oracle Database itself on a separate Oracle Linux or RHEL host, and on the Ubuntu IDP host install only the Instant Client so the IDP can connect remotely.

This page covers the Ubuntu side: Instant Client install plus JDBC driver placement. The actual Oracle Database setup (preinstall, oracle-database-ee-19c, PDB, listener, moadmin user) is identical to the Oracle Linux 8 flow on the remote DB host.

2.1 Confirm the remote Oracle target

Before starting, you should have a reachable Oracle 19c host with:

A pluggable database called ORCLPDB1 open and saved
A listener on TCP port 1521
A moadmin user inside ORCLPDB1 with CONNECT, RESOURCE, DBA
Network reachability from the Ubuntu IDP host (firewall, route, no NAT issues)

If you do not yet have such a host, follow the Oracle Linux 8 → Oracle runbook on the target server first.

2.2 Install prerequisite packages

sudo apt install -y libaio1 unzip wget alien

alien lets you convert Oracle’s RPM Instant Client packages into .deb if you prefer; the Instant Client also ships a zip variant which is simpler.

2.3 Download Oracle Instant Client 19c (Basic + SQL*Plus + JDBC)

Download these three zips from Oracle’s Instant Client page (login required) to /tmp/:

instantclient-basic-linux.x64-19.x.x.x.x.zip
instantclient-sqlplus-linux.x64-19.x.x.x.x.zip
instantclient-jdbc-linux.x64-19.x.x.x.x.zip

2.4 Extract to `/opt/oracle`

sudo mkdir -p /opt/oracle
cd /opt/oracle
sudo unzip -o /tmp/instantclient-basic-linux.x64-*.zip
sudo unzip -o /tmp/instantclient-sqlplus-linux.x64-*.zip
sudo unzip -o /tmp/instantclient-jdbc-linux.x64-*.zip
ls /opt/oracle

You should see a single directory like /opt/oracle/instantclient_19_23/.

2.5 Configure environment and linker

INSTANT_CLIENT_DIR=$(ls -d /opt/oracle/instantclient_19_* | head -1)

sudo tee /etc/profile.d/oracle.sh > /dev/null <<EOF
export LD_LIBRARY_PATH=${INSTANT_CLIENT_DIR}:\$LD_LIBRARY_PATH
export PATH=${INSTANT_CLIENT_DIR}:\$PATH
EOF
sudo chmod +x /etc/profile.d/oracle.sh
source /etc/profile.d/oracle.sh

echo "${INSTANT_CLIENT_DIR}" | sudo tee /etc/ld.so.conf.d/oracle-instantclient.conf
sudo ldconfig

2.6 Verify the client

Replace <oracle-host> with the IP or hostname of the remote Oracle DB.

sqlplus moadmin/Password123@//<oracle-host>:1521/ORCLPDB1 <<< 'SELECT 1 FROM dual;'

You should see 1 returned. If you see TNS:could not resolve the connect identifier, your network path to the Oracle host is blocked.

2.7 Place the Oracle JDBC driver

The Instant Client JDBC zip extracts ojdbc8.jar into the same instantclient directory. Copy it into /opt/miniorange/drivers/.

INSTANT_CLIENT_DIR=$(ls -d /opt/oracle/instantclient_19_* | head -1)
sudo mkdir -p /opt/miniorange/drivers
sudo cp ${INSTANT_CLIENT_DIR}/ojdbc8.jar /opt/miniorange/drivers/
sudo chmod 644 /opt/miniorange/drivers/ojdbc8.jar

Values for the `/initialize` wizard

Important. Use Service Name, not SID. The IDP schema lives in the PDB (ORCLPDB1).

Field	Value
Database Type	Oracle
Host	`<oracle-host>` (the remote DB IP)
Port	`1521`
SID / Service	Service
Service Name	`ORCLPDB1`
Username	`moadmin`
Password	`Password123`

Section 3

Erlang + RabbitMQ

RabbitMQ is used by the IDP for internal messaging between microservices. It requires Erlang. On Ubuntu, both are installed from the official Cloudsmith-hosted apt repositories curated by the RabbitMQ team.

Note. RabbitMQ is not bundled with mo-installer and must be installed before running the installer.

3.1 Install Erlang prerequisites

sudo apt install -y curl gnupg apt-transport-https

3.2 Add Erlang and RabbitMQ signing keys

# RabbitMQ signing key
sudo curl -fsSL https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc | \
  sudo gpg --dearmor -o /usr/share/keyrings/com.rabbitmq.team.gpg

# Erlang (Cloudsmith) key
sudo curl -fsSL https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key | \
  sudo gpg --dearmor -o /usr/share/keyrings/io.cloudsmith.rabbitmq.E495BB49CC4BBE5B.gpg

# RabbitMQ server (Cloudsmith) key
sudo curl -fsSL https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key | \
  sudo gpg --dearmor -o /usr/share/keyrings/io.cloudsmith.rabbitmq.9F4587F226208342.gpg

3.3 Add the Cloudsmith apt sources

sudo tee /etc/apt/sources.list.d/rabbitmq.list > /dev/null <<'SOURCES'
## Erlang
deb [signed-by=/usr/share/keyrings/io.cloudsmith.rabbitmq.E495BB49CC4BBE5B.gpg] \
  https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bookworm main
deb-src [signed-by=/usr/share/keyrings/io.cloudsmith.rabbitmq.E495BB49CC4BBE5B.gpg] \
  https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bookworm main

## RabbitMQ server
deb [signed-by=/usr/share/keyrings/io.cloudsmith.rabbitmq.9F4587F226208342.gpg] \
  https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu bookworm main
deb-src [signed-by=/usr/share/keyrings/io.cloudsmith.rabbitmq.9F4587F226208342.gpg] \
  https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu bookworm main
SOURCES

sudo apt update

3.4 Install Erlang

sudo apt install -y \
  erlang-base erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
  erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
  erlang-runtime-tools erlang-snmp erlang-ssl erlang-syntax-tools \
  erlang-tftp erlang-tools erlang-xmerl

3.5 Install RabbitMQ

sudo apt install -y rabbitmq-server --fix-missing

3.6 Enable and start the service

sudo systemctl enable --now rabbitmq-server
sudo systemctl status rabbitmq-server

3.7 Enable the management plugin

sudo rabbitmq-plugins enable rabbitmq_management
sudo systemctl restart rabbitmq-server

3.8 Verify

sudo rabbitmqctl status
sudo ss -tulnp | grep 5672

Values for the `/initialize` wizard

Field	Value
RabbitMQ Host	`127.0.0.1`
AMQP Port	`5672`
Mgmt UI Port	`15672`
Default Login	`guest` / `guest`

Section 4

mo-installer

The miniOrange installer bundles Java 17 and Redis. You don’t install either manually. The installer auto-detects the OS and deploys the IDP services into /opt/tomcat/.

4.1 Download the installer

cd /opt
sudo wget https://miniorange.s3.us-east-1.amazonaws.com/public/installers/mo-installer-5.0.0.zip
sudo unzip mo-installer-5.0.0.zip -d mo-installer-5.0.0
cd /opt/mo-installer-5.0.0
ls -la

4.2 Source the environment file

less .env.sh
source .env.sh

Note. In v5.0.0, .env.sh does not contain database connection details. The DB connection is configured later through the browser UI at /initialize.

4.3 Set execute permissions

sudo chmod +x mo-installer.sh moctl/*.sh

4.4 Run the installer

sudo bash mo-installer.sh

The installer covers:

Java 17 — installed automatically
Redis — installed and configured automatically
moctl — installed to /usr/bin/moctl with tab completion
IDP services — deployed to /opt/tomcat/

Ubuntu note. The installer scripts use apt on Debian-family systems. If you see dpkg lock errors, ensure no unattended-upgrades job is running: sudo systemctl status unattended-upgrades.

At the end of the run:

Next step: moctl service start

4.5 Start the four core services

moctl service start

Service	Port	Purpose
configserver	8071	Configuration
eurekaserver	8070	Service registry
gatekeeper	8072	API gateway
miniorange	8080	Main IDP service

4.6 Check service status

moctl service status

Symbol	Meaning
`● running`	Active and registered in Eureka
`△ registering`	Active but not yet registered; wait and recheck
`△ stopped`	Inactive
`✗ failed`	Check `moctl log <service>`

4.7 Open `/initialize` in a browser

https://<SERVER_IP>/initialize

Past the self-signed certificate warning, enter the values from the Database section above, plus Redis (127.0.0.1:6379, no password by default) and RabbitMQ (Section 3 values).

After the wizard completes, the dashboard loads. Navigate to Settings → Base URL and set it to your final domain.

4.8 Restart all services

moctl service restart

This starts the secondary services that depend on the completed schema. Wait 1–2 minutes for everything to register.

Section 5

Verify & Service Enablement

5.1 Full service status

moctl service status

Every service should show ● running or ● reachable. If a service shows △ registering, wait 30 seconds and re-run.

5.2 Full diagnostics

moctl diagnose

Expected output includes:

Database connectivity reachable
Redis reachable
RabbitMQ reachable

5.3 Individual service status

sudo systemctl status mo-idp-miniorange.service
sudo systemctl status redis
sudo systemctl status rabbitmq-server

5.4 Check all bound ports

sudo ss -tulnp | egrep '8080|8070|8071|8072|6379|5672'

For your DB:

DB	Port	Listening on
PostgreSQL	5432	127.0.0.1
MySQL	3306	127.0.0.1
MSSQL	1433	0.0.0.0
Oracle	1521	remote host

5.5 Preflight

moctl pre

Quick `moctl` reference

Command	Purpose
`moctl service start`	Start all services in order
`moctl service stop`	Stop all services in reverse order
`moctl service restart`	Full ordered restart
`moctl service restart miniorange`	Restart one named service
`moctl log <service> -f`	Live tail logs
`moctl log <service> --since 1h`	Logs from the past hour
`moctl system memory`	Per-service RSS memory
`moctl jvm <service>`	Heap, threads, open file descriptors

Common issues on Ubuntu

Issue: Could not get lock /var/lib/dpkg/lock-frontend

unattended-upgrades is running. Wait for it to finish, or stop it temporarily:

sudo systemctl stop unattended-upgrades

Issue: PostgreSQL connection refused on 127.0.0.1

The pg_hba.conf edit didn’t reload. Run:

sudo systemctl restart postgresql@16-main

Issue: ufw blocking inter-service traffic

The IDP microservices talk to each other on 127.0.0.1 (which ufw always allows), but if you’ve set up custom rules, verify:

sudo ufw status verbose

Issue: ldconfig not finding Oracle Instant Client libraries

ls /etc/ld.so.conf.d/ | grep oracle
sudo ldconfig -v 2>&1 | grep -i oracle

The /etc/ld.so.conf.d/oracle-instantclient.conf file must exist and point to the instantclient directory.

Issue: Tomcat stale PID after a crash

sudo rm -f /opt/tomcat/latest/temp/*.pid
moctl service restart miniorange

System Prep

1.1 Update the system

1.2 Install required utilities

1.3 Configure the firewall

1.4 AppArmor

Database

2.1 Add the PGDG apt repository

2.2 Install PostgreSQL 16

2.3 Start the service

2.4 Create the miniOrange database and user

2.5 Switch authentication to md5

2.6 Open the PostgreSQL port (only if remote access is needed)

2.7 Verify

Values for the /initialize wizard

2.1 Add the MySQL APT repository

2.2 Install MySQL 8.4

2.3 Start and enable the service

2.4 Secure the installation (optional but recommended)

2.5 Create the miniOrange database and user

2.6 Place the MySQL JDBC driver (derived assumption)

2.7 Open the MySQL port (only if remote access is needed)

2.8 Verify

Values for the /initialize wizard

What this means

JDBC-driver-only path on Debian 12

Values for the /initialize wizard (remote MSSQL host)

2.1 Confirm the remote Oracle target

2.2 Install prerequisite packages

2.3 Download Oracle Instant Client 19c (Basic + SQL*Plus + JDBC)

2.4 Extract to /opt/oracle

2.5 Configure environment and linker

2.6 Verify the client

2.7 Place the Oracle JDBC driver

Values for the /initialize wizard

Erlang + RabbitMQ

3.1 Install Erlang prerequisites

3.2 Add Erlang and RabbitMQ signing keys

3.3 Add the Cloudsmith apt sources

3.4 Install Erlang

3.5 Install RabbitMQ

3.6 Enable and start the service

3.7 Enable the management plugin

3.8 Verify

Values for the /initialize wizard

mo-installer

4.1 Download the installer

4.2 Source the environment file

4.3 Set execute permissions

4.4 Run the installer

4.5 Start the four core services

4.6 Check service status

4.7 Open /initialize in a browser

4.8 Restart all services

Verify & Service Enablement

5.1 Full service status

5.2 Full diagnostics

5.3 Individual service status

5.4 Check all bound ports

5.5 Preflight

Quick moctl reference

Common issues on Ubuntu

Values for the `/initialize` wizard

Values for the `/initialize` wizard

Values for the `/initialize` wizard (remote MSSQL host)

2.4 Extract to `/opt/oracle`

Values for the `/initialize` wizard

Values for the `/initialize` wizard

4.7 Open `/initialize` in a browser

Quick `moctl` reference