Differences

This shows you the differences between two versions of the page.

--- baseraspberrypisetupbookworm [2026/10/26 16:08] – [12. Add startup cleanup and recovery] tputman
+++ baseraspberrypisetupbookworm [2026/10/27 16:55] (current) – tputman
@@ Line 4: / Line 4: @@
 Complete this setup before installing MIX or the TransSECS built deployment.
+This guide was validated using a **Raspberry Pi 4 with Raspberry Pi OS Bookworm Legacy 64-bit Lite** installed through Raspberry Pi Imager. Current MIX and TransSECS deployments were validated on this system using **Java 25**. Sections describing Raspberry Pi 5 hardware, command-line imaging, or MIX-specific network configuration are retained as reference information but were not part of this validation.
 ===== 1. Hardware =====
@@ Line 9: / Line 11: @@
 For a new installation, use a **Raspberry Pi 4 or Raspberry Pi 5**.
-A TransSECS Devices system can normally run on a 1 GB Pi or better (2 GB or 4 GB, for example). If the Raspberry Pi will also display a MIX or MIStudio user interface in a browser, use **4 GB or more**.
+A TransSECS Devices system can normally run on a 1 GB Pi or better (2 GB or 4 GB, for example). If the Raspberry Pi will also display a MIX user interface in a browser, use **4 GB or more**.
 If your Raspberry Pi came with an OS installed on its microSD Card, you may start with this installation or you may start with a new SD Card and keep this bundled SD Card for reference.
@@ Line 73: / Line 75: @@
 ===== 3. Command-line image setup alternative =====
+This section is an alternative for experienced Linux users and was not part of the Raspberry Pi 4 validation described above.
 Experienced Linux users may write a downloaded ''%%.img.xz%%'' image directly using their normal Linux imaging workflow.
@@ Line 81: / Line 85: @@
 sudo touch /media/$USER/bootfs/ssh
 echo "mix:$(echo 'ErgoErgo' | openssl passwd -6 -stdin)" | sudo tee /media/$USER/bootfs/userconf.txt
-sudo umount /media/$USER/bootfs
 </code>
+The boot partition mount path varies by Linux distribution. Replace ''%%/media/$USER/bootfs%%'' with the actual mount point of the SD card's ''%%bootfs%%'' partition if necessary.
+Safely unmount or eject the microSD card before removing it from the computer.
 After the first login, set the hostname and correct time zone:
@@ Line 180: / Line 187: @@
 ==== Wired Ethernet ====
-For a TransSECS-only system using wired Ethernet:
+For a system using wired Ethernet:
 <code text>
@@ Line 247: / Line 254: @@
 Choose **Network Configuration**.
+This MIX setup-page method was not part of the base Raspberry Pi validation described above.
 ===== 6. Check the hostname configuration =====
@@ Line 469: / Line 478: @@
 These changes do not prevent an administrator from installing updates manually later. Updates can still be performed deliberately during a maintenance period after they have been reviewed and tested.
-===== 10. Install Java 8 =====
+===== 10. Install Java 25 =====
-ErgoTech applications covered by this guide use **Java 8** unless ErgoTech support specifies otherwise.
+Current MIX and TransSECS deployments validated with this guide require **Java 25**.
-For a 64-bit Raspberry Pi OS installation:
+The validated Raspberry Pi installation used **Azul Zulu OpenJDK 25.0.3 LTS for ARM64**.
+The Java installation used during validation is:
 <code text>
-cd /tmp
+/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
-wget -O java8.tar.gz "https://api.adoptium.net/v3/binary/latest/8/ga/linux/aarch64/jre/hotspot/normal/eclipse"
-sudo mkdir -p /opt/java
-sudo tar -xzf java8.tar.gz -C /opt/java
-ls /opt/java
 </code>
-The ''%%ls%%'' command shows the folder which was extracted.
+Create the Java installation directory if it does not already exist:
-For example, the folder may look similar to:
+<code text>
+sudo mkdir -p /opt/java
+</code>
+Install or extract the approved Java 25 ARM64 package under:
 <code text>
-jdk8u504-b01-jre
+/opt/java
 </code>
-The exact Java version changes over time. Use the **actual folder name shown by ''%%ls /opt/java%%''** in the next command rather than copying the example version literally.
+If the Java package is supplied as a ''%%.tar.gz%%'' archive, extract it into ''%%/opt/java%%'' and then check the resulting directory name.
 For example:
 <code text>
-sudo update-alternatives --install /usr/bin/java java /opt/java/jdk8u504-b01-jre/bin/java 100
+cd /tmp
+wget -O zulu25.tar.gz "https://cdn.azul.com/zulu/bin/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64.tar.gz"
+sudo mkdir -p /opt/java
+sudo tar -xzf zulu25.tar.gz -C /opt/java
+ls /opt/java
 </code>
-Replace ''%%jdk8u504-b01-jre%%'' with the directory which was actually extracted on the system.
+For the validated installation, the Java directory is:
-Verify the Java version:
 <code text>
-java -version
+zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
 </code>
-The version should begin with:
+Verify Java directly from that installation:
 <code text>
-openjdk version "1.8.0_
+/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java -version
 </code>
-Also verify which Java executable is selected:
+The validated installation reports:
 <code text>
-readlink -f /usr/bin/java
+openjdk version "25.0.3"
+OpenJDK Runtime Environment Zulu25.34+17-CA
+OpenJDK 64-Bit Server VM Zulu25.34+17-CA
 </code>
-The path should point to the Java 8 installation under:
+Also verify that the Java executable exists:
 <code text>
-/opt/java/
+ls -l /opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java
 </code>
-If Java 17, Java 21, or another version is still selected:
+MIX and TransSECS select this Java installation explicitly.
+MIX uses ''%%MIX_JAVA_HOME%%'':
 <code text>
-sudo update-alternatives --config java
+MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
 </code>
-Choose the Java 8 entry under ''%%/opt/java%%'', then run:
+A TransSECS deployment can use the same Java installation by placing its ''%%bin%%'' directory first in ''%%PATH%%'':
 <code text>
-java -version
+PATH=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin:$PATH
-readlink -f /usr/bin/java
 </code>
-again to verify the selection.
+The MIX and TransSECS installation procedures configure these Java settings when their services are installed.
-==== Java 11 when specifically required ====
+It is not necessary to change the Raspberry Pi's system-wide ''%%java%%'' selection for MIX or TransSECS to use Java 25.
-Only install or select Java 11 when ErgoTech support specifically requires it.
+Java 8 is not required as part of the current Raspberry Pi base setup. During current TransSECS validation, the deployed runtime could not start using Java 8 because the deployed classes require Java 25.
-The required Java 11 build or configuration may depend on the ErgoTech application being deployed. Use the Java 11 version and installation instructions supplied by ErgoTech support rather than automatically installing the latest Java 11 release.
+Older ErgoTech software releases may have different Java requirements. Follow the requirements for the specific software release when maintaining an older system.
 ===== 11. Keep Linux system logs from filling the SD card =====
@@ Line 566: / Line 582: @@
 The exact layout can vary between Raspberry Pi OS versions.
-On current Raspberry Pi OS Bookworm Lite, the configuration may contain one combined block similar to:
+On the Bookworm Lite system used for this validation, the configuration contained one combined block similar to:
 <code text>
@@ Line 589: / Line 605: @@
 </code>
-In this layout, there may be no existing ''%%size%%'' or ''%%maxsize%%'' setting and ''%%/var/log/daemon.log%%'' may not exist.
+There was no existing ''%%size%%'' or ''%%maxsize%%'' setting and ''%%/var/log/daemon.log%%'' was not present.
 Edit the configuration:
@@ Line 597: / Line 613: @@
 </code>
-For the combined Bookworm block, add:
+For this combined Bookworm block, add:
 <code text>
@@ Line 623: / Line 639: @@
 </code>
-If the system uses a different rsyslog layout with separate log blocks and existing ''%%size%%'' or ''%%maxsize%%'' settings, set the applicable system-log limits to **20M** while preserving the existing layout.
+If the system uses a different rsyslog layout with separate log blocks and existing ''%%size%%'' or ''%%maxsize%%'' settings, preserve that layout rather than creating log files which do not already exist.
 Do not create ''%%/var/log/daemon.log%%'' solely because it is not present.
-Do not change the other logrotate settings.
 Save with **Ctrl+O**, **Enter**, **Ctrl+X**.
@@ Line 639: / Line 653: @@
 The ''%%-d%%'' option is a safe debug check. It does not actually rotate the logs.
-For a configuration using ''%%maxsize 20M%%'', the output should contain a line similar to:
+For the validated configuration using ''%%maxsize 20M%%'', the output contained a line similar to:
 <code text>
@@ Line 649: / Line 663: @@
 ==== Limit the systemd journal ====
-Also cap the systemd journal at 50 MB:
+Cap the systemd journal at 50 MB:
 <code text>
@@ Line 671: / Line 685: @@
 </code>
-The current journal may be much smaller than 50 MB. The setting limits future growth; it does not require the journal to already be near that size.
+The journal on the validated system was well below this limit. The setting limits future growth; it does not require the journal to already be near 50 MB.
 ===== 12. Add startup cleanup and recovery =====
-''%%/etc/rc.local%%'' is a traditional Linux startup script which runs near the end of the boot process. On a Raspberry Pi it is useful for small recovery and housekeeping tasks after a power interruption.
+''%%/etc/rc.local%%'' is a traditional Linux startup script which is useful for small recovery and housekeeping tasks after a power interruption.
-On Raspberry Pi OS Bookworm Lite, ''%%/etc/rc.local%%'' may not exist on a fresh installation. The systemd compatibility service is already provided and will automatically run ''%%/etc/rc.local%%'' at boot when the file exists and is executable.
+On the Bookworm Lite system used for this validation, ''%%/etc/rc.local%%'' did not exist initially. Raspberry Pi OS already provided the systemd compatibility service needed to run the file once it existed and was executable.
 Check whether the file already exists:
@@ Line 697: / Line 711: @@
 </code>
-Replace the file with:
+Use:
 <code text>
@@ Line 718: / Line 732: @@
 chmod 1777 /tmp
-# Remove old compressed Linux system logs
+# Remove compressed logs older than 7 days
-find /var/log -maxdepth 1 -type f \
+find /var/log -name "*.gz" -mtime +7 -delete
-  \( -name "syslog*.gz" \
-  -o -name "daemon.log*.gz" \
-  -o -name "auth.log*.gz" \
-  -o -name "kern.log*.gz" \
-  -o -name "messages*.gz" \) \
-  -mtime +7 \
-  -delete \
-# Trim oversized active Linux system logs
+# Trim oversized Linux system logs
-find /var/log -maxdepth 1 -type f \
+find /var/log -maxdepth 1 -type f
-  \( -name "syslog" \
+  \( -name "syslog*"
-  -o -name "daemon.log" \
+  -o -name "daemon.log*"
-  -o -name "auth.log" \
+  -o -name "auth.log*"
-  -o -name "kern.log" \
+  -o -name "kern.log*"
-  -o -name "messages" \) \
+  -o -name "messages*" \)
-  -size +20M \
+  -size +20M
   -exec truncate -s 5M {} \;
@@ Line 778: / Line 785: @@
 The test should complete without shell errors. The maintenance log should contain a start time, disk-usage information, and a finish time.
-''%%rc-local.service%%'' is a static compatibility service on Raspberry Pi OS Bookworm. It does not need to be enabled manually. Once ''%%/etc/rc.local%%'' exists and is executable, systemd will run it automatically during boot.
+On the validated Bookworm system, ''%%rc-local.service%%'' was a static compatibility service and did not need to be enabled manually. Once ''%%/etc/rc.local%%'' existed and was executable, it ran automatically during boot.
 Reboot to verify automatic startup:
@@ Line 793: / Line 800: @@
 </code>
-The service should show:
+The validated system showed:
 <code text>
@@ Line 808: / Line 815: @@
 The Pi 5 has a built-in real-time clock. With the official RTC battery installed, it can retain the time while power is off.
+This Raspberry Pi 5 path was not part of the Raspberry Pi 4 validation described above.
 Check:
@@ Line 821: / Line 830: @@
 These models do not have a battery-backed real-time clock. ''%%fake-hwclock%%'' saves an approximate time which Linux can restore after a power interruption.
-On Raspberry Pi OS Bookworm, ''%%fake-hwclock%%'' is installed with a systemd service and an hourly save task. ErgoTech systems save the clock more frequently so that less time is lost after an unexpected power interruption.
+On the Raspberry Pi 4 used for validation, ''%%fake-hwclock%%'' was installed with a systemd service and an hourly save task. ErgoTech systems save the clock more frequently so that less time is lost after an unexpected power interruption.
 Save the clock every five minutes:
@@ Line 870: / Line 879: @@
 </code>
-On a Raspberry Pi 3 or 4, ''%%RTC time: n/a%%'' is normal because these models do not have a battery-backed real-time clock.
+On the Raspberry Pi 4 used for validation, ''%%RTC time: n/a%%'' was normal.
 Verify that the time zone is correct and that the system clock is synchronized when a network time source is available.
-If the factory network has no Internet or local time server, the clock may drift. MIX provides another convenient way to set the system time by loading **Get Pre-License Key** on the setup page. In addition, for SECS/GEM tool applications, the host can also set the Pi's clock by sending the standard **S2F31 Date and Time Set Request** message. This updates the system clock in the same way as opening the MIX Get Pre-License Key page updates it from the browser.
 ===== 14. Verify the base setup =====
@@ Line 887: / Line 894: @@
 <code text>
-java -version
+/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java -version
-readlink -f /usr/bin/java
 cat /var/log/ergotech-boot-maintenance.log
 df -h /
@@ Line 898: / Line 904: @@
 Verify:
-  * Java reports version ''%%1.8.0_...%%''.
+  * Java 25 starts successfully from ''%%/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64%%''.
-  * ''%%/usr/bin/java%%'' resolves to the Java 8 installation under ''%%/opt/java%%''.
+  * Java reports version ''%%25.0.3%%'' for the validated installation.
   * The boot-maintenance log contains a new start and finish entry from the reboot.
   * The root filesystem has plenty of free space.
@@ Line 926: / Line 932: @@
 If a fixed IP address was configured, reconnect using that address after the reboot to confirm that the network configuration persisted.
-At this point the SD card can be preserved as a **completed base image** before TransSECS or MIX is installed. Before cloning the image onto multiple Raspberry Pis, follow the ErgoTech cloning procedure to reset device-specific identity information.
+At this point the SD card can be preserved as a **completed base image** before TransSECS or MIX is installed.
 Before removing the SD card, shut the Pi down cleanly: