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
docs: add UTM VM setup guide for macOS developers (#42)
* docs: add UTM VM setup guide for macOS developers
Add instructions and scripts for running Hypeman in a UTM virtual machine
with nested KVM virtualization on Apple Silicon Macs (M3+ required).
- Add scripts/utm/README.md with step-by-step UTM VM setup guide
- Add scripts/utm/download-iso.sh to download Ubuntu Server ARM64 ISO
- Add scripts/utm/setup-vm.sh to provision VM with Hypeman dependencies
- Update DEVELOPMENT.md with note directing macOS users to UTM guide
- Add .gitignore entry for downloaded ISO files
- Minor markdown formatting improvements in DEVELOPMENT.md
* refactor: rename setup-vm.sh to bootstrap-dev-environment.sh
Clarifies that this script sets up a dev environment for working on
Hypeman, not a VM running inside Hypeman.
* bind to 0.0.0.0 option for lgtm
Copy file name to clipboardExpand all lines: DEVELOPMENT.md
+60-35Lines changed: 60 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,8 @@ This document covers development setup, configuration, and contributing to Hypem
4
4
5
5
## Prerequisites
6
6
7
+
> **macOS Users:** Hypeman requires KVM, which is only available on Linux. See [scripts/utm/README.md](scripts/utm/README.md) for instructions on setting up a Linux VM with nested virtualization on Apple Silicon Macs.
|`CADDY_LISTEN_ADDRESS`| Address for Caddy ingress listeners |`0.0.0.0`|
104
+
|`CADDY_ADMIN_ADDRESS`| Address for Caddy admin API |`127.0.0.1`|
105
+
|`CADDY_ADMIN_PORT`| Port for Caddy admin API |`2019`|
106
+
|`CADDY_STOP_ON_SHUTDOWN`| Stop Caddy when hypeman shuts down (set to `true` for dev) |`false`|
107
+
|`ACME_EMAIL`| Email for ACME certificate registration (required for TLS ingresses) |_(empty)_|
108
+
|`ACME_DNS_PROVIDER`| DNS provider for ACME challenges: `cloudflare`|_(empty)_|
109
+
|`ACME_CA`| ACME CA URL (empty = Let's Encrypt production) |_(empty)_|
110
+
|`TLS_ALLOWED_DOMAINS`| Comma-separated allowed domains for TLS (e.g., `*.example.com,api.other.com`) |_(empty)_|
111
+
|`DNS_PROPAGATION_TIMEOUT`| Max time to wait for DNS propagation (e.g., `2m`) |_(empty)_|
112
+
|`DNS_RESOLVERS`| Comma-separated DNS resolvers for propagation checking |_(empty)_|
113
+
|`CLOUDFLARE_API_TOKEN`| Cloudflare API token (when using `cloudflare` provider) |_(empty)_|
109
114
110
115
**Important: Subnet Configuration**
111
116
@@ -114,10 +119,12 @@ The default subnet `10.100.0.0/16` is chosen to avoid common conflicts. Hypeman
114
119
If you need a different subnet, set `SUBNET_CIDR` in your environment. The gateway is automatically derived as the first IP in the subnet (e.g., `10.100.0.0/16` → `10.100.0.1`).
115
120
116
121
**Alternative subnets if needed:**
122
+
117
123
-`172.30.0.0/16` - Private range between common Docker (172.17.x.x) and cloud provider (172.31.x.x) ranges
118
124
-`10.200.0.0/16` - Another private range option
119
125
120
126
**Example:**
127
+
121
128
```bash
122
129
# In your .env file
123
130
SUBNET_CIDR=172.30.0.0/16
@@ -128,23 +135,30 @@ SUBNET_CIDR=172.30.0.0/16
128
135
`UPLINK_INTERFACE` tells Hypeman which host interface to use for routing VM traffic to the outside world (for iptables MASQUERADE rules). On many hosts this is `eth0`, but laptops and more complex setups often use Wi‑Fi or other names.
129
136
130
137
**Quick way to discover it:**
138
+
131
139
```bash
132
140
# Ask the kernel which interface is used to reach the internet
133
141
ip route get 1.1.1.1
134
142
```
143
+
135
144
Look for the `dev` field in the output, for example:
145
+
136
146
```text
137
147
1.1.1.1 via 192.168.12.1 dev wlp2s0 src 192.168.12.98
138
148
```
149
+
139
150
In this case, `wlp2s0` is the uplink interface, so you would set:
151
+
140
152
```bash
141
153
UPLINK_INTERFACE=wlp2s0
142
154
```
143
155
144
156
You can also inspect all routes:
157
+
145
158
```bash
146
159
ip route show
147
160
```
161
+
148
162
Pick the interface used by the default route (usually the line starting with `default`). Avoid using local bridges like `docker0`, `br-...`, `virbr0`, or `vmbr0` as the uplink; those are typically internal virtual networks, not your actual internet-facing interface.
149
163
150
164
### TLS Ingress (HTTPS)
@@ -154,6 +168,7 @@ Hypeman uses Caddy with automatic ACME certificates for TLS termination. Certifi
Run Hypeman in a UTM virtual machine with nested KVM virtualization on Apple Silicon Macs.
4
+
5
+
> **Note:** In the future, this dev environment setup may be automated using Ansible or similar tooling.
6
+
7
+
## Requirements
8
+
9
+
-**macOS 15 (Sequoia)** or later
10
+
-**Apple M3 or newer** chip (required for nested virtualization)
11
+
-**UTM 4.6+**: `brew install --cask utm`
12
+
13
+
## Setup
14
+
15
+
### 1. Download Ubuntu Server ISO
16
+
17
+
Download Ubuntu Server for ARM from [Ubuntu's website](https://ubuntu.com/download/server/arm).
18
+
19
+
Or use the helper script:
20
+
21
+
```bash
22
+
./download-iso.sh
23
+
```
24
+
25
+
### 2. Create VM in UTM
26
+
27
+
Follow the [official UTM Ubuntu guide](https://docs.getutm.app/guides/ubuntu/):
28
+
29
+
1. Open UTM and click **+** to **Create a New Virtual Machine**
30
+
1. Start: select **Virtualize**
31
+
1. Operating System: select **Linux**
32
+
1. Hardware: Set RAM to **8192 MiB** and CPU cores to **4**
33
+
1. Linux: check the box to **Use Apple Virtualization**. **Boot from ISO** should be the default. Click **Browse** and select the Ubuntu Server ISO.
34
+
1. Storage: Set disk size to **100 GiB**
35
+
1. Shared Directory: skip this. The `bootstrap-dev-environment.sh` script will clone Hypeman onto the VM.
36
+
1. Summary: Name the VM **Hypeman** and click **Save**
37
+
38
+
**Important:** Before starting the VM:
39
+
40
+
- Right-click **HypemanDev** → **Edit**
41
+
- Go to **System** → Check **Use Hypervisor** (enables nested virtualization)
42
+
- Save
43
+
44
+
### 3. Install Ubuntu Server
45
+
46
+
Start the VM and follow the Ubuntu installer. You can select the defaults for everything except the following:
47
+
48
+
1. Profile configuration: set up with your name, a hostname like `hypeman` and a linux username and password you can remember.
49
+
1.**Install OpenSSH Server** ← Important to select this and then **Import SSH key** → **from GitHub** → Enter your GitHub username to import your public keys. The result is that, assuming your host machine has a private key that is uploaded to GitHub, you can re-use this for sshing into the VM.
50
+
51
+
Once installation is complete, select **Reboot now**.
52
+
53
+
### 4. Find VM IP Address
54
+
55
+
After reboot, the VM console will ask you to log in with the Linux username and password you set up.
56
+
Once you do that and have a shell, run:
57
+
58
+
```bash
59
+
ip addr
60
+
```
61
+
62
+
Look for an IP like `192.168.x.x` on the `enp0s1` interface.
63
+
64
+
Open a terminal window on your host machine and export it: `export HYPEMAN_VM_IP=192.168.x.x`
65
+
66
+
### 5. SSH into the VM
67
+
68
+
From your Mac terminal:
69
+
70
+
```bash
71
+
ssh -A -i ~/.ssh/id_ed25519 yourusername@${HYPEMAN_VM_IP}
72
+
```
73
+
74
+
### 6. Configure SSH (Recommended)
75
+
76
+
Add this to your `~/.ssh/config`, replacing `192.168.x.x` with your VM's IP and `yourusername` with your Ubuntu username:
77
+
78
+
```
79
+
Host hypeman
80
+
HostName 192.168.x.x
81
+
User yourusername
82
+
IdentityFile ~/.ssh/id_ed25519
83
+
ForwardAgent yes
84
+
```
85
+
86
+
Now you can simply run:
87
+
88
+
```bash
89
+
ssh hypeman
90
+
```
91
+
92
+
## Setting up the VM for Hypeman Development
93
+
94
+
Copy the `bootstrap-dev-environment.sh` script into the VM and run it:
95
+
96
+
```bash
97
+
scp bootstrap-dev-environment.sh hypeman:
98
+
ssh hypeman
99
+
./bootstrap-dev-environment.sh
100
+
```
101
+
102
+
This installs Go, erofs-utils, dnsmasq, and other dependencies needed for Hypeman.
103
+
104
+
It also clones the main Hypeman repositories into ~/code.
105
+
106
+
## Development Workflow
107
+
108
+
### Cursor Remote-SSH
109
+
110
+
Cursor can run on your host machine and connect to the VM to edit files and run commands.
111
+
112
+
1. Open Command Palette (`Cmd+Shift+P`)
113
+
2. Run **Remote-SSH: Connect to Host...**
114
+
3. Type **hypeman** (from your SSH config)
115
+
4. Open the `~/code/hypeman` directory.
116
+
117
+
### Run Hypeman
118
+
119
+
Follow the directions in [../../DEVELOPMENT.md](../../DEVELOPMENT.md).
120
+
121
+
You might want to set up your host machine's `/etc/hosts` file to resolve `hypeman.local` to your VM's IP:
122
+
123
+
```
124
+
192.168.x.x hypeman.local
125
+
```
126
+
127
+
This will let you, for example, run the LGTM stack in the VM (according to the instructions in [../../DEVELOPMENT.md](../../DEVELOPMENT.md)) and then on your host machine, open http://hypeman.local:3000 to view the Grafana dashboard.
128
+
129
+
It will also let you test ingresses with subdomain routing.
130
+
131
+
### Hypeman CLI on host -> VM
132
+
133
+
The Hypeman CLI can be installed on your host machine and used to interact with the VM.
134
+
135
+
1. Install the CLI on your host machine (or build from source):
0 commit comments