Skip to content

standalone.md

Latest commit

 

History

History
233 lines (157 loc) · 5.75 KB

standalone.md

File metadata and controls

233 lines (157 loc) · 5.75 KB
Raw

Standalone

The community provides an experimental standalone/lightweight bootable container image including MicroShift, the Jumpstarter {term}operator, and a small web UI.

This is ideal for small development environments, and small labs. For production deployments where High Availability is desired see Production.

Prerequisites

  • An Intel device, capable of running Centos 10
  • At least 4GB RAM and 40GB disk space recommended

Install

Method 1: create a centos install iso with a kickstart.ks config attached

From a linux system, for example fedora:

export CENTOS_ISO=CentOS-Stream-10-latest-x86_64-boot.iso
curl -o "${CENTOS_ISO}" "https://mirrors.centos.org/mirrorlist?path=/10-stream/BaseOS/x86_64/iso/${CENTOS_ISO}&redirect=1&protocol=https"
curl -o kickstart.ks https://raw.githubusercontent.com/jumpstarter-dev/jumpstarter/refs/heads/main/controller/deploy/microshift-bootc/kickstart.ks
mkksiso kickstart.ks ${CENTOS_ISO} cs10-js-install.iso

Flash the .iso to a pendrive, and boot/install your system, watch out and remove the pendrive once install has finished.

Method 2: using system-reinstall-bootc

From a bootc capable system (Fedora or Centos 10), run the following command, please note that this action is destructive and will re-install your system.

sudo dnf -y install system-reinstall-bootc
sudo system-reinstall-bootc quay.io/jumpstarter-dev/microshift/bootc:latest
sudo reboot

Setup

Once installed and booted, the system displays a banner with the HTTP management interface URL, for example: http://jumpstarter.192.168.1.11.nip.io:8880/

The default password for root will be jumpstarter and you will be requested to change it on the first connection.

Network

The system uses nip.io for automatic DNS resolution (e.g. jumpstarter.10.0.2.2.nip.io) although you can setup your own domain if you have control over your DNS.

Port Service Description
80 HTTP MicroShift ingress
443 HTTPS MicroShift API and ingress
8880 Config UI Web configuration interface
6443 API Server Kubernetes API (internal)

Security

  1. Default Password: root:jumpstarter. Console login forces a change. Web UI requires a change before access.
  2. TLS Certificates: This deployment uses self-signed certs by default.
  3. Authentication: Web UI uses PAM authentication with root credentials.

Development

This section covers working with and modifying the bootc image for development purposes.

Prerequisites

  • Fedora/RHEL-based system (tested on Fedora 42)
  • Podman installed and configured
  • Root/sudo access required for privileged operations
  • At least 4GB RAM and 20GB disk space recommended

Build the Bootc Image

From the controller/deploy/microshift-bootc/ directory:

make bootc-build

To build for multiple architectures (amd64 and arm64):

make bootc-build-multi

Test in a Container

Run MicroShift in a privileged container for testing:

make bootc-run

This creates a 1GB LVM disk image, starts MicroShift in a privileged container, sets up LVM volume groups for TopoLVM, and waits for MicroShift to be ready.

Access the services:

  • Configuration Web UI: http://localhost:8880 (login: root / jumpstarter)
  • MicroShift API: https://jumpstarter.<your-ip>.nip.io:6443
  • Pod Monitoring: http://localhost:8880/pods

Check running pods:

sudo podman exec -it jumpstarter-microshift-okd oc get pods -A

Build Bootable Images

Create a QCOW2 image for VMs or bare-metal deployments:

make build-image

Create an ISO installer image:

make build-iso
If the container is running, stop it first with `make bootc-rm` to avoid LVM conflicts.

The images are configured via config.toml with LVM partitioning (20GB minimum), XFS root filesystem, and default password root:jumpstarter.

Build Kickstart ISO

To create a kickstart ISO that automates the installation:

make download-centos-iso  # Downloads CentOS Stream 10 ISO
make build-ks-iso          # Creates kickstart ISO

For ARM64 builds:

make download-centos-iso ARCH=aarch64
make build-ks-iso ARCH=aarch64

Development Workflow

For iterative development of the web UI without rebuilding the entire image:

make bootc-reload-app

This copies the updated Python modules and templates into the running container and restarts the config service.

Shell Access

Open a shell in the running container:

make bootc-sh

Troubleshooting

LVM/TopoLVM Issues

sudo podman exec jumpstarter-microshift-okd vgs
sudo podman exec jumpstarter-microshift-okd pvs
make bootc-rm && make clean && make bootc-run

MicroShift Not Starting

sudo podman logs jumpstarter-microshift-okd
sudo podman exec jumpstarter-microshift-okd journalctl -u microshift -f

Configuration Service Issues

sudo podman exec jumpstarter-microshift-okd systemctl status config-svc
sudo podman exec jumpstarter-microshift-okd journalctl -u config-svc -f

Cleanup

Stop and remove the container:

make bootc-rm

Remove all build artifacts and images:

make clean

Customization

Override the default image tag:

BOOTC_IMG=quay.io/your-org/microshift-bootc:v1.0 make bootc-build

Add Kubernetes manifests by editing the kustomization.yaml file in controller/deploy/microshift-bootc/manifests/ - they will be deployed to /etc/microshift/manifests.d/002-jumpstarter/ in the image.

Push to Registry

Push single-architecture image:

make bootc-push

Push multi-architecture manifest:

make bootc-push-multi