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

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

These instructions install MIX in:

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

MIX requires **Java 25**.

The validated Raspberry Pi installation used:

<code text>
/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
</code>

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

The MIX setup page is:

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

After an MIStudio project is deployed, the validated application URL is:

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

===== 1. Copy the MIX runtime to the Raspberry Pi =====

On the Windows computer, open PowerShell and change to the MIX installation directory for the software release being deployed.

For example:

<code text>
Set-Location "C:\ET\<release>\MIX"
</code>

Create the MIX runtime directory on the Raspberry Pi:

<code text>
ssh mix@<Pi-address> "mkdir -p /home/mix/mixruntime"
</code>

Copy the contents of the MIX runtime directory:

<code text>
scp -r .\* mix@<Pi-address>:/home/mix/mixruntime/
</code>

After the copy completes, connect to the Pi:

<code text>
ssh mix@<Pi-address>
</code>

Verify the runtime files:

<code text>
ls -la /home/mix/mixruntime
ls -la /home/mix/mixruntime/scripts
</code>

The MIX runtime should contain files and directories including:

<code text>
mix.jar
mix.properties
htmlroot/
lib/
log4j/
logs/
scripts/
security/
</code>

The Linux startup script is:

<code text>
/home/mix/mixruntime/scripts/MIX.sh
</code>

Make the Linux scripts executable:

<code text>
chmod +x /home/mix/mixruntime/scripts/MIX.sh
chmod +x /home/mix/mixruntime/scripts/stopmix.sh
chmod +x /home/mix/mixruntime/scripts/restartmix.sh
</code>

If the copied MIX installation contains an ''%%ErgoIOTLicense_*.lic%%'' file from another computer, remove or move that file before starting MIX.

Each Raspberry Pi must use the runtime license associated with that Pi.

===== 2. Verify Java 25 =====

Verify the Java installation:

<code text>
/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java -version
</code>

The validated installation reports:

<code text>
openjdk version "25.0.3"
</code>

MIX can use this Java installation directly without changing the Raspberry Pi's system-wide Java default.

===== 3. Start MIX manually =====

Change to the MIX runtime directory:

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

Start MIX with Java 25:

<code text>
MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64 \
./scripts/MIX.sh
</code>

Startup output should identify the MIX installation, Java executable, and configured port.

For example:

<code text>
MIX_INSTALL_DIR:  /home/mix/mixruntime
MIX_WORK_DIR:     /home/mix/mixruntime
MIX properties:   /home/mix/mixruntime/mix.properties
Java executable:  /opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java
Native libraries: /home/mix/mixruntime/lib
Debug port:       18050
</code>

MIX should also report:

<code text>
mix.port:7226
</code>

and its MIX build number.

If a Raspberry Pi runtime license has not yet been installed, MIX will display the system's pre-license key:

<code text>
Initializing MIX runtime with prelicense key: <pre-license-key>
</code>

Keep this key for the license request.

===== 4. Install the Raspberry Pi runtime license =====

Each Raspberry Pi requires an ErgoTech runtime license associated with that system.

The pre-license key is shown during MIX startup. It can also be viewed from the MIX setup page:

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

Select **Get Pre-License Key** and send the displayed key to ErgoTech.

Copy the license provided for the Raspberry Pi into:

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

The filename may include the pre-license key, for example:

<code text>
ErgoIOTLicense_<pre-license-key>.lic
</code>

If TransSECS has already been licensed on the same Raspberry Pi using the same pre-license key, the Pi-specific ErgoIOT runtime license can also be copied into the MIX runtime directory.

Start MIX again:

<code text>
cd /home/mix/mixruntime

MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64 \
./scripts/MIX.sh
</code>

Verify that startup contains:

<code text>
Valid IOT System Runtime License detected.
</code>

===== 5. Verify the MIX web server =====

While MIX is running, verify that port 7226 is listening:

<code text>
sudo ss -ltnp | grep 7226
</code>

A normal result contains:

<code text>
LISTEN ... *:7226 ... java
</code>

From a browser on another computer, open:

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

Verify that the MIX setup page loads.

===== 6. Deploy an MIStudio project to the Raspberry Pi =====

In MIStudio, select the project's **MIX Target**.

Configure the target with the Raspberry Pi address.

For example:

<code text>
Host Name:      <Pi-address>
Mix Login Name: ergouser
Port:           7226
Target Name:    MIX
</code>

Enter the configured MIX password.

Save the MIStudio project and select **Deploy**.

During a successful deployment, MIX should:

  * authenticate the MIStudio deployment request,
  * stop the currently loaded application logic,
  * replace the deployed application files,
  * receive the new ''%%VIBLogic.jar%%'' and application files,
  * reload the application logic,
  * continue running without requiring the MIX process to be stopped manually.

After deployment, open:

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

Verify that the newly deployed application loads.

The MIX console should show the deployment files being received and the application logic being reloaded.

===== 7. Stop the manual MIX process =====

Before configuring automatic startup, stop the manually started MIX process.

If MIX is running in the foreground, press:

<code text>
Ctrl+C
</code>

Verify that no MIX HeadlessController process remains:

<code text>
pgrep -af 'com.ergotech.mix.server.HeadlessController'
</code>

No output should be returned.

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

Create the log directory if it does not already exist:

<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=mix
WorkingDirectory=/home/mix/mixruntime
Environment="MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64"
ExecStart=/bin/sh /home/mix/mixruntime/scripts/MIX.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**.

Reload systemd, enable MIX at boot, and start it:

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

Verify the service:

<code text>
systemctl status mix --no-pager
</code>

Look for:

<code text>
Active: active (running)
</code>

Verify the MIX Java process:

<code text>
pgrep -af 'com.ergotech.mix.server.HeadlessController'
</code>

The process should use:

<code text>
/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java
</code>

Verify that MIX is listening on port 7226:

<code text>
sudo ss -ltnp | grep 7226
</code>

===== 9. Verify MIX console logging =====

MIX console output is written to:

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

Verify:

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

Check the MIX build, pre-license key, and license result:

<code text>
grep -E "Running MIX Build|Valid IOT System Runtime License detected|Initializing MIX runtime" \
/home/mix/mixruntime/logs/runmix-console.log | tail -n 10
</code>

A successfully licensed startup should contain lines similar to:

<code text>
Running MIX Build <build-number>
Initializing MIX runtime with prelicense key: <pre-license-key>
Valid IOT System Runtime License detected.
</code>

Verify the console log file:

<code text>
ls -l /home/mix/mixruntime/logs/runmix-console.log
</code>

With the validated systemd configuration, the active console log was created as:

<code text>
root root
</code>

===== 10. 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 {
    su root root
    size 5M
    rotate 5
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}
</code>

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

Check the rule:

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

A normal result mentions:

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

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

To verify the rule completely, force one rotation:

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

Check the result:

<code text>
ls -lh /home/mix/mixruntime/logs/runmix-console.log*
systemctl status mix --no-pager
pgrep -af 'com.ergotech.mix.server.HeadlessController'
</code>

The previous console contents should be copied to:

<code text>
runmix-console.log.1
</code>

The active ''%%runmix-console.log%%'' should be truncated while the same MIX process remains running.

Generate a new request:

<code text>
curl -s -o /dev/null http://127.0.0.1:7226/setup.html
sleep 2
</code>

Verify that the active log receives new output:

<code text>
ls -lh /home/mix/mixruntime/logs/runmix-console.log*
tail -n 10 /home/mix/mixruntime/logs/runmix-console.log
</code>

A successful test should show:

<code text>
Default Servlet : GET Request: /setup.html
</code>

===== 11. Reboot and verify MIX =====

Reboot:

<code text>
sudo reboot
</code>

After the Raspberry Pi comes back online, reconnect:

<code text>
ssh mix@<Pi-address>
</code>

Verify that MIX started automatically:

<code text>
systemctl status mix --no-pager
</code>

Verify the MIX Java process:

<code text>
pgrep -af 'com.ergotech.mix.server.HeadlessController'
</code>

Verify port 7226:

<code text>
sudo ss -ltnp | grep 7226
</code>

Verify that the current boot started MIX and accepted the runtime license:

<code text>
grep -E "Running MIX Build|Valid IOT System Runtime License detected|Initializing MIX runtime" \
/home/mix/mixruntime/logs/runmix-console.log | tail -n 10
</code>

Verify:

  * MIX is ''%%active (running)%%''.
  * MIX is running with Java 25.
  * Port 7226 is listening.
  * The current MIX build started successfully.
  * The Raspberry Pi runtime license is accepted.
  * ''%%runmix-console.log%%'' contains startup messages from the current boot.

Finally, open:

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

and verify that the deployed application is available after the reboot.

At this point MIX is installed, licensed, configured for automatic startup, accepting MIStudio deployments, serving the deployed application, and rotating its console log correctly.