Skip to content

Commit 2bf61b3

Browse files
author
HenkVanHoek
committed
This commit introduces a comprehensive, professional-grade automation and testing suite for the release process of the project.
Key improvements include: - **New `release.py` Commands:** The release script is now a multi-command tool with a two-stage workflow (`release` and `finalize`) to separate CI builds from local mastering. - **Windows Installer:** A new `package` command and Inno Setup script (`installer.iss`) have been added to create a professional `setup.exe` for Windows users. - **Unit and Integration Tests:** A full suite of tests (`pytest`) has been implemented for the release process: - Unit tests for the `release.py` internal logic of the script. - Integration tests for the PyInstaller build process. - Integration tests for the Inno Setup packaging process. - **Documentation:** The `README.md` and `CONTRIBUTING.md` files have been updated to reflect the new installation methods and the complete, robust release workflow.
1 parent 7dd3b0f commit 2bf61b3

File tree

8 files changed

+504
-145
lines changed

8 files changed

+504
-145
lines changed

‎CONTRIBUTING.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,24 @@ To get started with developing the scripts locally, follow these steps:
3838

3939
pip install requests pytest bump2version
4040

41+
## Setting Up the Release Mastering Environment
42+
43+
While day-to-day development of the Python scripts can be done on any operating system (Windows, macOS, or Linux), creating an official, complete release requires a **Windows environment**. This is because the final steps of the process involve packaging the Windows installer and exporting the master VirtualBox appliance.
44+
45+
This environment can be a physical Windows PC or, for developers on other platforms, a dedicated Windows Virtual Machine.
46+
47+
To set up your mastering environment, you will need to install the following software **inside your Windows environment**:
48+
49+
1. **Git for Windows**
50+
2. **Python 3.11**
51+
3. **`uv`** (e.g., via `pipx install uv`)
52+
4. **Project Dependencies** (run `uv pip install -e .[dev]` in the project root)
53+
5. **Oracle VirtualBox for Windows**
54+
6. **Inno Setup 6** (from [jrsoftware.org](https://jrsoftware.org/isinfo.php))
55+
7. **GitHub CLI** (`gh`)
56+
57+
Before you can run the `finalize` command, you must first use the `create-master-vm` tool within this environment to generate the `pi-master-template` that VirtualBox will use for the export.
58+
4159
## Submitting Changes (Pull Requests)
4260

4361
1. Create a new branch for your feature or bugfix. For example:
@@ -52,4 +70,4 @@ To get started with developing the scripts locally, follow these steps:
5270
4. Open a **Pull Request** from your branch to the **main** branch of the original repository.
5371
5. Please provide a clear description of the changes you have made in the Pull Request.
5472

55-
Thank you again for your contribution!
73+
Thank you again for your contribution!

‎README.md‎

Lines changed: 53 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,83 @@
11
# Pi Server VM
22

3-
A set of cross-platform Python scripts to fully automate the creation and cloning of secure, minimal Debian virtual machines in **Oracle VirtualBox**. This project is designed to emulate a Raspberry Pi server environment, making it ideal for testing server software, network configurations, or any project designed for a Raspberry Pi without needing physical hardware.
3+
A set of cross-platform tools to fully automate the creation and management of secure, minimal Debian virtual machines in **Oracle VirtualBox**. This project is designed to emulate a Raspberry Pi server environment, making it ideal for testing server software, network configurations, or any project designed for a headless server without needing physical hardware.
44

55
## Features
66

7-
- **Cross-Platform:** The tools work on Windows, macOS, and Linux.
8-
- **LAN Accessible:** Creates virtual machines as full citizens on your local network, discoverable and accessible from any other computer.
9-
- **Idempotent "Golden Master":** The master template is self-healing and can be safely started and updated without breaking the cloning process.
10-
- **Intelligent & Configurable Cloning:** Cloned VMs automatically configure a unique hostname on first boot. Optional command-line flags allow customization of RAM, CPUs, secondary disks, username, and password.
11-
- **Network Discoverable:** Clones announce themselves on the local network using Avahi (mDNS), appearing as **hostname.local**, just like a real Raspberry Pi.
12-
- **User-Friendly Console:** The IP address of the VM is displayed on the console login screen for easy, immediate SSH access.
13-
- **Secure by Default:** The template is configured with a locked root account and a standard user with **sudo** privileges whose password must be changed on first login (if not set during cloning).
7+
This project provides a complete ecosystem for virtual machine management, from creation to deployment.
148

15-
## Compatibility
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.
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.
1613

17-
This project provides pre-built executables for Windows, macOS, and Linux. They are built and tested to run on the following operating systems **or newer**:
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.
17+
- **Cross-Platform Tools:** All command-line tools are provided as standalone executables for Windows, macOS, and Linux.
1818

19-
* **Windows:** Windows 10
20-
* **macOS:** macOS 10.15 (Catalina)
21-
* **Linux:** Ubuntu 22.04 (glibc 2.35)
19+
#### VM & Network Features
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.
22+
- **User-Friendly Console:** The IP address of the VM is displayed directly on the console login screen for immediate, easy SSH access.
23+
- **Secure by Default:** The master template is configured with a locked root account and a standard user with **sudo** privileges.
24+
25+
---
26+
27+
## Installation
28+
29+
### Windows (Recommended)
30+
31+
For the easiest and most reliable setup, use the provided installer.
32+
33+
1. Navigate to the **[latest release page](https://github.com/HenkVanHoek/pi-server-vm/releases/latest)**.
34+
2. Under the "Assets" section, download the installer, which will be named pi-server-vm-setup-vX.X.X.exe.
35+
3. Run the downloaded setup.exe and follow the on-screen instructions.
36+
37+
> **Note on Security Warnings:** The Windows installer is not yet digitally code-signed. Therefore, you may see a security warning from Windows Defender SmartScreen when you run it. Please click **"More info"** and then **"Run anyway"** to proceed with the installation. The executables are built transparently via our public GitHub Actions workflow for your security.
2238
23-
While the tools may work on other Linux distributions, they are officially tested against Ubuntu 22.04.
39+
### macOS & Linux
2440

25-
## Downloads
41+
1. Navigate to the **[latest release page](https://github.com/HenkVanHoek/pi-server-vm/releases/latest)**.
42+
2. Download the appropriate archive for your OS (executables-macOS.tar.gz or executables-Linux.tar.gz).
43+
3. Extract the archive. This will create a folder for each tool.
44+
4. It is recommended to move these tool folders to a convenient location and add their parent directory to your system PATH for easy access.
2645

27-
For users who want to skip the manual installation, a ready-to-use virtual appliance (**ova** file) is available.
46+
---
2847

29-
➡️ **[Download the latest release (v1.4.1)](https://github.com/HenkVanHoek/pi-server-vm/releases/latest)**
3048
## Quick Start & Usage
3149

32-
This project provides executables for easy use. For detailed, step-by-step instructions for your specific operating system, please see the guides below. These guides are the recommended starting point.
33-
For all 3 environments, the Anti-Virus software will very likely block the executables. Sometimes silently. Be aware of this.
50+
For detailed, step-by-step instructions for your specific operating system, including how to handle potential anti-virus warnings, please see the full guides:
3451

3552
- ➡️ **[Installation Guide for Windows](INSTALL_WINDOWS.md)**
3653
- ➡️ **[Installation Guide for macOS](INSTALL_MACOS.md)**
3754
- ➡️ **[Installation Guide for Linux](INSTALL_LINUX.md)**
3855

56+
---
57+
58+
## Compatibility
59+
60+
The pre-built executables are tested to run on the following operating systems or newer:
61+
62+
* **Windows:** Windows 10
63+
* **macOS:** macOS 10.15 (Catalina)
64+
* **Linux:** Ubuntu 22.04 (glibc 2.35)
65+
66+
---
67+
3968
## Scope and Limitations
4069

4170
It is important to understand what this project is designed for and what its limitations are.
4271

43-
### CPU Emulation vs. Allocation
44-
The virtual machines run on the **x86-64 architecture** of your host computer, not the **ARM architecture** of a physical Raspberry Pi. This is excellent for testing the performance of **multithreaded** server applications in a **multicore** environment, but it cannot run software that is compiled exclusively for ARM.
72+
* **CPU Architecture:** The virtual machines run on the **x86-64 architecture** of your host computer, not the **ARM architecture** of a physical Raspberry Pi. This is excellent for testing multi-threaded server applications but cannot run software compiled exclusively for ARM.
73+
* **Real-Time Processing:** This virtual environment is **not suitable for hard real-time applications** that require microsecond-precision timing or direct hardware access like GPIO pins.
4574

46-
### Real-Time Processing
47-
This virtual environment is **not suitable for hard real-time applications** that require microsecond-precision timing or direct hardware access like GPIO pins.
75+
---
4876

4977
## Contributing
50-
We welcome contributions! Please see the **CONTRIBUTING.md** file for details on how to get started, report bugs, and submit changes.
78+
We welcome contributions! Please see the **[CONTRIBUTING.md](CONTRIBUTING.md)** file for details on how to get started, report bugs, and submit changes.
5179

5280
## Support This Project
53-
If you find this project useful and would like to help support its continued development, please consider becoming a sponsor. Your support is greatly appreciated!
81+
If you find this project useful, please consider becoming a sponsor. Your support is greatly appreciated!
5482

5583
➡️ **[Sponsor @HenkVanHoek on GitHub](https://github.com/sponsors/HenkVanHoek)**

‎installer.iss‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
; installer.iss
2+
; Inno Setup script for the Pi-Server-VM Tools project.
3+
4+
[Setup]
5+
; --- Basic Application Information ---
6+
AppName=Pi-Server-VM Tools
7+
; The version is passed in from our release.py script
8+
AppVersion={#MyVersion}
9+
AppPublisher=PiSelfhosting
10+
DefaultDirName={autopf}\Pi-Server-VM Tools
11+
DefaultGroupName=Pi-Server-VM Tools
12+
13+
; --- Installer Output ---
14+
; The final setup-x.x.x.exe will be placed in the 'dist' directory
15+
OutputBaseFilename=pi-server-vm-setup-{#MyVersion}
16+
OutputDir=./dist
17+
Compression=lzma
18+
SolidCompression=yes
19+
WizardStyle=modern
20+
21+
[Files]
22+
; This is the most important section.
23+
; It tells the installer to take all the directories and files from our
24+
; PyInstaller build output ('dist' folder) and package them.
25+
Source: "dist\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs
26+
27+
[Icons]
28+
; This section creates the Start Menu shortcuts for the user.
29+
Name: "{group}\Create Master VM"; Filename: "{app}\create-master-vm\create-master-vm.exe"
30+
Name: "{group}\Clone VM"; Filename: "{app}\clone-vm\clone-vm.exe"
31+
Name: "{group}\Web App"; Filename: "{app}\pi-selfhosting-web\pi-selfhosting-web.exe"
32+
Name: "{group}\Uninstall Pi-Server-VM Tools"; Filename: "{uninstallexe}"

0 commit comments

Comments
 (0)