Docs Blog Apps Pricing

Getting Started

1. Install the CLI 2. Login 3. Build and Push 4. Boot on GCP 5. Boot on Bare Metal

Guides

Authentication Pushing and Pulling Images Configuring Images Working with Hosts Working with GCP Working with Bare Metal latitude.sh OVHcloud Working with AWS Backups Tips and Tricks

CLI Reference

kheeper auth kheeper authorizations kheeper bots kheeper clouds kheeper contexts kheeper hosts kheeper images kheeper orgs kheeper push kheeper releases kheeper status

Boot on GCP

This guide walks through booting your first Kheeper-managed host on Google Cloud Platform.

Prerequisites

Set the variables in your shell needed for the remaining steps.

ORG=$(kheeper orgs list | grep 'user-[0-9a-f]' | awk '{ print $1 }')
PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get project) --format='value(projectNumber)')
HOST=getting-started-gcp

Alternatively you can find your project number (not project ID) in the [GCP Console] (https://console.cloud.google.com/welcome).

Step 1 — Connect your GCP project

Link your GCP project to your Kheeper org so that instances in that project can auto-register as hosts.

kheeper clouds create ${ORG}/my-gcp --project-number ${PROJECT_NUMBER}

Step 2 — Create a GCE instance

First, create a firewall rule to allow HTTPS traffic to instances tagged https.

gcloud compute firewall-rules create allow-https \
  --allow tcp:80,tcp:443 \
  --target-tags allow-https

Then launch a VM using the public Kheeper GCE image. This image is a Fedora bootc image that automatically connects to the Kheeper registry on first boot.

gcloud compute instances create ${HOST} \
  --project $(gcloud config get project) \
  --zone us-central1-a \
  --image-family fedora-bootc \
  --image-project kheeper \
  --machine-type c4-standard-2 \
  --boot-disk-size 40GB \
  --tags=allow-https \
  --metadata=kheeper-region=us.kheeper.com

Step 3 — Verify

The instance will boot and auto-register within a few minutes. Then check that the host appeared:

kheeper hosts list --org ${ORG}

You should see a host whose instance name matches the VM you created.

Step 4 — Author the config

Generate a starter config from the image's schema and edit it to fit your host. If you used the example Caddy image from the build-and-push guide, it expects domain and name fields:

kheeper releases start config.json --image us.kheeper.com/${ORG}/getting-started:v1

Set domain to ${HOST}.${ORG}.us.kheeper.app — every Kheeper host gets a <host>.<org>.us.kheeper.app DNS record (region-scoped) that points at its public IP, so Caddy can request a TLS cert for it automatically.

Step 5 — Create a release

Create a release that pairs the image with your config:

kheeper releases create ${ORG}/${HOST}:v1 \
  --image us.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.

Step 7 — Verify

Once the host has rebooted, curl the domain you set in the config:

curl https://${HOST}.${ORG}.us.kheeper.app/

Troubleshooting

gcloud compute instances tail-serial-port-output ${HOST}

Clean up

Delete the GCE instance and Kheeper host when you're done:

gcloud compute instances delete ${HOST} --zone us-central1-a --quiet
kheeper hosts delete ${ORG}/${HOST}