You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+26Lines changed: 26 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -60,6 +60,32 @@ Your development environment is now complete. You can verify that everything is
60
60
61
61
If all tests pass, your environment is perfectly configured, and you are ready to start developing.
62
62
63
+
## Core Architectural Concepts
64
+
65
+
This section explains some of the key design patterns used in the project.
66
+
67
+
### Host-to-Guest Communication and First-Boot Provisioning
68
+
69
+
A key feature of this project is the ability to customize a cloned VM on its first boot. This is achieved through a robust, two-part mechanism using **VirtualBox Guest Properties**, which is the official and recommended method for passing data from the host machine to the guest VM.
70
+
71
+
This avoids fragile and insecure methods like direct filesystem injection.
72
+
73
+
**1. Host-Side (The "Sender")**
74
+
75
+
- The **scripts/vm_manager.py** script is responsible for all direct interaction with the VirtualBox command-line tools.
76
+
- In the **clone_vm** function, after a new VM is cloned, the script sets several Guest Properties using the **VBoxManage guestproperty set** command.
77
+
- For example, it creates the content for the PiSelfhosting identity file and injects it into the **/VirtualBox/GuestAdd/PiSelfhostingInfo** property for that specific VM.
78
+
79
+
**2. Guest-Side (The "Receiver")**
80
+
81
+
- The **pi-master-template** is a "smart" image. It contains a one-shot **systemd** service located at **/etc/systemd/system/pivm-info.service**.
82
+
- On the very first boot of a new clone, this service runs a script located at **/usr/local/bin/pivm-info-writer.sh**.
83
+
- This script uses the **VBoxControl guestproperty get** command (which is part of the VirtualBox Guest Additions) to read the data that the host has set.
84
+
- It then writes this data to the final destination file (e.g., **/etc/piselfhosting-virtual-pi-server**).
85
+
- As its final step, the script disables its own systemd service, ensuring it will never run again on subsequent boots.
86
+
87
+
This architecture allows for a clean separation of concerns and provides a flexible and secure way to provision new VMs with unique identities.
88
+
63
89
## Submitting Changes (Pull Requests)
64
90
65
91
1. Create a new branch for your feature or bugfix (`git checkout -b feature/my-new-feature`).
Copy file name to clipboardExpand all lines: README.md
+6-7Lines changed: 6 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,22 +7,21 @@ A set of cross-platform tools to fully automate the creation and management of s
7
7
This project provides a complete ecosystem for virtual machine management, from creation to deployment.
8
8
9
9
#### Core Functionality
10
-
-**Automated Master Template Creation:** A command-line tool, create-master-vm, that downloads the latest Debian ISO and builds a "golden master" VM template from scratch.
11
-
-**One-Command Cloning:** A tool, clone-vm, to create new, independent development VMs from the master template in seconds.
10
+
-**Automated Master Template Creation:** A command-line tool, **create-master-vm**, that downloads the latest Debian ISO and builds a "golden master" VM template from scratch.
11
+
-**One-Command Cloning:** A tool, **clone-vm**, to create new, independent development VMs from the master template in seconds.
12
12
-**Web UI for VM Creation:** A simple web interface to create and customize new clone VMs directly from your browser, without needing to use the command line.
13
13
14
14
#### Professional User Experience
15
-
-**Professional Windows Installer:** A single, easy-to-use setup.exe for a one-click setup on Windows, complete with Start Menu shortcuts.
16
-
-**Pre-Built Virtual Appliance:** A ready-to-import .ova file is included in each release, allowing users on any platform to get started instantly without building the template themselves.
15
+
-**Professional Windows Installer:** A single, easy-to-use **setup.exe** for a one-click setup on Windows, complete with Start Menu shortcuts.
16
+
-**Pre-Built Virtual Appliance:** A ready-to-import **.ova** file is included in each release, allowing users on any platform to get started instantly without building the template themselves.
17
17
-**Cross-Platform Tools:** All command-line tools are provided as standalone executables for Windows, macOS, and Linux.
18
18
19
19
#### VM & Network Features
20
20
-**LAN Accessible:** Cloned VMs are configured as full citizens on your local network, discoverable and accessible from any other computer.
21
-
-**Network Discovery (mDNS):** Clones announce themselves on the network using Avahi, appearing as hostname.local, just like a real Raspberry Pi.
21
+
-**Network Discovery (mDNS):** Clones announce themselves on the network using Avahi, appearing as **hostname.local**, just like a real Raspberry Pi.
22
22
-**User-Friendly Console:** The IP address of the VM is displayed directly on the console login screen for immediate, easy SSH access.
23
23
-**Secure by Default:** The master template is configured with a locked root account and a standard user with **sudo** privileges.
24
-
25
-
---
24
+
-**Ecosystem Integration:** Each clone is automatically provisioned with a unique identity file at **/etc/piselfhosting-virtual-pi-server**. This file contains the model name, a unique serial number, and the hostname, allowing for easy discovery and management by other tools in the PiSelfhosting ecosystem, such as the **pi-scanner**.
0 commit comments