Here’s a detailed breakdown of the global_software section for the CodexMCP Alpha Stage Prototype. This is an early-stage deployment configuration, focusing on automation and infrastructure setup. Each line is designed to ensure that the system is fully prepared before any other services are deployed.

CodexMCP Alpha: Global Software Initialization

Overview

The global_software section defines core setup steps that every VM follows during provisioning. This ensures:

• Disks are fully expanded and available.
• System logging is properly installed and configured.
• Basic system services are initialized before specialized configurations are applied.

At this stage, everything is a working prototype, meaning this is what works right now for our setup, but it will evolve as we refine CodexMCP.

Disk Expansion – Ensuring Full Use of Allocated Space

  - "echo 1 | sudo tee /sys/class/block/sda/device/rescan > /dev/null"

• Triggers a rescan of the disk so Linux detects any size changes.
• This is necessary because Proxmox initially presents the VM disk with its original (pre-expanded) size.

  - "sudo growpart /dev/sda 3"

• Expands partition /dev/sda3 to use all available disk space.
• growpart is part of cloud-utils, ensuring that the partition itself matches the resized virtual disk.

  - "sudo pvresize /dev/sda3"

• Adjusts the Physical Volume (PV) so it recognizes the newly available space.
• This step is required for LVM (Logical Volume Manager) to allocate additional storage.

  - "sudo lvextend -l +100%FREE $(sudo lvs --noheadings -o lv_path | awk '{print $1}')"

• Extends the Logical Volume (LV) to use all free space in the volume group.
• Uses $(sudo lvs --noheadings -o lv_path | awk '{print $1}') to dynamically locate the correct logical volume.

  - "sudo resize2fs $(sudo lvs --noheadings -o lv_path | awk '{print $1}')"

• Resizes the filesystem (ext4) so that it fully utilizes the newly expanded logical volume.
• If using XFS instead of ext4, this would be xfs_growfs instead.

System Preparation – Installing & Configuring Logging

  - "sudo apt update && sudo apt install -y rsyslog"

• Ensures rsyslog is installed for system logging.
• Required for capturing and forwarding logs to the centralized log server.

  - "sudo systemctl enable rsyslog && sudo systemctl start rsyslog"

• Enables and starts the rsyslog service on boot.
• Ensures logs are properly handled as soon as the system initializes.

  - "if [[ \"$(hostname)\" != \"logs-core-1\" ]]; then echo '*.* @{{LOGGING_SERVER_IP}}:514;RSYSLOG_ForwardFormat' | sudo tee /etc/rsyslog.d/50-remote.conf > /dev/null; fi"

• Prevents the logging server (logs-core-1) from sending logs to itself.
• On all other nodes, this:
  • Configures rsyslog to forward all logs (*.*) to the central logging server ({{LOGGING_SERVER_IP}}) on port 514.
  • Uses RSYSLOG_ForwardFormat, a standardized format for log forwarding.

  - "sudo systemctl restart rsyslog"

• Restarts rsyslog so all changes take effect immediately.

Why This Matters

• The disk expansion process ensures that each VM gets its full allocated storage at boot.
• Rsyslog installation standardizes log collection across all infrastructure components.
• The log forwarding condition prevents the logging server from entering a loop by sending logs to itself.

This forms the core system preparation layer before deploying specialized services like OpenSearch, MariaDB, and network components.

Next Steps

With global_software documented, we will move on to detailing the specific infrastructure components, starting with the rsyslog server setup. Each part of the stack will be documented similarly, ensuring transparency and clarity in how CodexMCP is being built from the ground up.