====== Installing MIX on a Raspberry Pi ======

Complete [[BaseRaspberryPiSetupBookworm]|Raspberry Pi Base Setup]] first.

These instructions assume MIX is installed in:

<code text>
/home/mix/mixruntime
</code>

The normal MIX web port is **7226** unless ''%%mix.port%%'' in ''%%mix.properties%%'' has been changed.

The normal addresses are:

<code text>
http://<Pi-address>:7226
http://<Pi-address>:7226/setup.html
</code>

The first opens the application interface. The second opens the MIX setup page.

===== 1. Install MIX =====

Install MIX using the ErgoTech MIX installation package or installation instructions.

When installation is complete, ''%%/home/mix/mixruntime%%'' should contain files including:

<code text>
runmix.sh
mix.jar
mix.properties
log4j.mix.xml
</code>

Make the startup script executable:

<code text>
chmod +x /home/mix/mixruntime/runmix.sh
</code>

===== 2. Run MIX automatically as a Linux service =====

Linux uses **systemd** to manage services. A MIX systemd service starts MIX automatically during boot and restarts it if the process stops.

MIX console output should also be redirected to its own file. This prevents Java console messages from filling Linux logs such as ''%%syslog%%'' and ''%%daemon.log%%''.

==== If no MIX service exists yet ====

Create the log directory:

<code text>
mkdir -p /home/mix/mixruntime/logs
</code>

Create:

<code text>
sudo nano /etc/systemd/system/mix.service
</code>

Paste:

<code text>
[Unit]
Description=MIX Service
After=network-online.target
Wants=network-online.target

[Service]
User=root
WorkingDirectory=/home/mix/mixruntime
ExecStart=/bin/sh /home/mix/mixruntime/runmix.sh
Restart=always
RestartSec=60
StandardOutput=append:/home/mix/mixruntime/logs/runmix-console.log
StandardError=append:/home/mix/mixruntime/logs/runmix-console.log

[Install]
WantedBy=multi-user.target
</code>

Save with **Ctrl+O**, **Enter**, **Ctrl+X**.

Then:

<code text>
sudo systemctl daemon-reload
sudo systemctl enable mix
sudo systemctl start mix
sudo systemctl status mix
</code>

Look for ''%%active (running)%%''. Press **q** to leave the status display.

==== If MIX already has a service ====

Do not replace a working service file merely to add console logging.

First inspect it:

<code text>
sudo systemctl cat mix.service
</code>

Create a systemd override directory:

<code text>
sudo mkdir -p /etc/systemd/system/mix.service.d
</code>

This is the standard Linux location for local changes to an existing service. It keeps the original MIX service definition unchanged.

Create:

<code text>
sudo nano /etc/systemd/system/mix.service.d/override.conf
</code>

Paste:

<code text>
[Service]
StandardOutput=append:/home/mix/mixruntime/logs/runmix-console.log
StandardError=append:/home/mix/mixruntime/logs/runmix-console.log
</code>

Save with **Ctrl+O**, **Enter**, **Ctrl+X**.

Apply and restart:

<code text>
sudo systemctl daemon-reload
sudo systemctl restart mix.service
</code>

Verify the complete effective configuration:

<code text>
sudo systemctl cat mix.service
</code>

===== 3. Verify MIX console logging =====

Run:

<code text>
tail -n 20 /home/mix/mixruntime/logs/runmix-console.log
</code>

You should see MIX and Java startup messages.

It is normal for ''%%/var/log/syslog%%'' to continue containing Linux messages, for example network or WiFi status messages. The important result is which MIX and Java console output now appears in ''%%runmix-console.log%%'' rather than repeatedly filling the Linux system logs.

===== 4. Get the MIX license =====

From a browser on a PC, open:

<code text>
http://<Pi-address>:7226/setup.html
</code>

Click **Get Pre-License Key**.

Send the displayed pre-license key to ErgoTech.

The ErgoTech license is associated with the individual system. Changing the hostname, IP address, or network configuration does not change the license.

Copy the ''%%ErgoIOTLicense.lic%%'' file which ErgoTech provides into:

<code text>
/home/mix/mixruntime
</code>

Then restart MIX:

<code text>
sudo systemctl restart mix
</code>

Opening **Get Pre-License Key** also provides a convenient way to update the Raspberry Pi’s date and time. This is useful on systems which do not have access to a network time server.

The same setup page contains **Network Configuration** for systems which use MIX to manage the Pi’s network settings.

===== 5. Limit the MIX console log =====

Create:

<code text>
sudo nano /etc/logrotate.d/runmix-console
</code>

Paste:

<code text>
/home/mix/mixruntime/logs/runmix-console.log {
    size 5M
    rotate 5
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
    create 0644 root root
}
</code>

Save with **Ctrl+O**, **Enter**, **Ctrl+X**.

Check it:

<code text>
sudo logrotate -d /etc/logrotate.d/runmix-console
</code>

A normal result mentions:

  * ''%%/home/mix/mixruntime/logs/runmix-console.log%%''
  * ''%%5242880 bytes%%'', which is 5 MB
  * ''%%5 rotations%%''

If the current file is smaller than 5 MB, ''%%logrotate%%'' will say the log does not need rotating. This is normal.

''%%MIX.log%%'' is already limited by MIX’s log4j configuration and does not need this additional rule.

===== 6. Reboot and verify MIX =====

<code text>
sudo reboot
</code>

After about a minute, reconnect and run:

<code text>
systemctl status mix
tail -n 20 /home/mix/mixruntime/logs/runmix-console.log
df -h /
ls -lh /var/log/syslog*
ls -lh /var/log/daemon.log*
cat /var/log/ergotech-boot-maintenance.log
</code>

Verify:

  * MIX is ''%%active (running)%%''.
  * ''%%runmix-console.log%%'' contains recent MIX messages.
  * The SD card has plenty of free space.
  * ''%%syslog%%'' and ''%%daemon.log%%'' are bounded.
  * The boot-maintenance log shows a successful run after the reboot.

If this SD card will become a master image, verify the complete system once more before imaging it.