Kheeper

Boot on Bare Metal

This guide walks through booting your first Kheeper-managed host on bare metal using iPXE. We'll use latitude.sh for on-demand bare metal servers with hourly billing, which means this tutorial can be completed for less than $1.

Prerequisites

Set the vars in your shell you'll need for the remaining steps:

ORG=$(kheeper orgs list | grep 'user-[0-9a-f]' | awk '{ print $1 }')

Step 1 — Create an iPXE token

Generate a one-time iPXE token for your org. The token is valid for 24 hours.

kheeper ipxe-tokens create ${ORG}

This prints a URL like:

https://kheeper.com/api/ipxe/kh_ipxe_...

Copy this URL — you'll use it in the next step.

Step 2 — Create a server on latitude.sh

  1. Sign up or log in at latitude.sh
  2. Click Create Server
  3. Pick the cheapest available server in your desired location
  4. Under Operating System, select Custom iPXE and enter:
#!ipxe
dhcp
chain http://kheeper.com/api/ipxe/kh_ipxe...
  1. Under Billing, select Hourly
  2. Click Deploy

latitude.sh server configuration

Step 3 — Verify

The server will take about ten minutes to boot. Then you can check that the host has joined your organization:

kheeper hosts list --org ${ORG}

The host name is likely to be an opaque string read from the server at /etc/machine-id. Set it as a var in your shell for the remaining steps.

HOST=<my host name>

Step 4 — Author the config

Create a config file with values for the image's template. If you used the example Caddy image from the build-and-push guide, it expects a Name field:

echo '{"Name":"world"}' > config.json

Step 5 — Create a release

Create a release that pairs the image with your config:

kheeper releases create ${ORG}/${HOST}:v1 \
  --image kheeper.com/${ORG}/getting-started:v1 \
  --config-file config.json

Step 6 — Activate the release

kheeper hosts activate ${ORG}/${HOST}:v1

The host will pick up the release within a minute, then pull and reboot. If you used the example Caddy image, verify by curling the machine's IP:

curl http://<machine-ip>/

Troubleshooting

iPXE chain fails immediately. Some bare metal providers don't run DHCP automatically before executing your iPXE script. Make sure your script includes dhcp before the chain command:

#!ipxe
dhcp
chain http://kheeper.com/api/ipxe/kh_ipxe...

"Operation not supported" when chaining. iPXE on some hardware or providers doesn't support HTTPS. Use http://kheeper.com/... instead of https://kheeper.com/... in your chain URL.