Skip to content

docs: improve standalone bootc installation documentation #841

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mangelajo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: improve standalone bootc installation documentation #841

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
222 changes: 150 additions & 72 deletions python/docs/source/getting-started/installation/service/standalone.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,108 @@
# Standalone

Lightweight deployment using MicroShift and a bootable container (bootc) image
with the Jumpstarter {term}`operator` pre-installed. Ideal for edge devices,
development environments, and small labs. For production deployments, see
[Production](production.md).
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](production.md).

## 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:

```console
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
Comment thread
coderabbitai[bot] marked this conversation as resolved.
```

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.

```console
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) |

Comment on lines +54 to +60

@coderabbitai coderabbitai Bot Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Align the port table with the API example.
The table says 443 serves the MicroShift API, but the next section points readers to :6443 for that API. Please make these entries consistent so operators know which port to open.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@python/docs/source/getting-started/installation/service/standalone.md` around
lines 54 - 60, The port table is inconsistent with the API example, since the
MicroShift API is shown on 443 in the table but referenced as 6443 elsewhere.
Update the standalone installation docs table in the port listing so the API
Server entry and the HTTPS/MicroShift API description match the `:6443` example,
and keep the descriptions in sync with the surrounding installation guidance.

@mangelajo mangelajo Jun 26, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

right 443 is ingress only

@coderabbitai coderabbitai Bot Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mangelajo Thanks for confirming — that matches the concern. 443 should be documented as ingress only, and 6443 should remain the Kubernetes API port so the table stays consistent with the example.

### 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

## Install
### Build the Bootc Image

### Build the Image
From the `controller/deploy/microshift-bootc/` directory:

```console
make bootc-build
```

### Run as Container
To build for multiple architectures (amd64 and arm64):

```console
make bootc-run
make bootc-build-multi
```

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.

### Create a Bootable QCOW2 Image
### Test in a Container

For bare-metal or VM deployments:
Run MicroShift in a privileged container for testing:

```console
make build-image
```

```{note}
If the container is running, stop it first with `make bootc-rm` to avoid LVM
conflicts.
make bootc-run
```

## Verify
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`,
password change required on first use)
- **Configuration Web UI**: `http://localhost:8880` (login: `root` / `jumpstarter`)
- **MicroShift API**: `https://jumpstarter.<your-ip>.nip.io:6443`
- **Pod Monitoring**: `http://localhost:8880/pods`

Expand All @@ -57,99 +112,122 @@ Check running pods:
sudo podman exec -it jumpstarter-microshift-okd oc get pods -A
```

## Configuration
### Build Bootable Images

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

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

Add Kubernetes manifests to `/etc/microshift/manifests.d/002-jumpstarter/` by
editing `kustomization.yaml`. For live config service changes without rebuild:
Create an ISO installer image:

```console
make bootc-reload-app
make build-iso
```

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

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

The QCOW2 image is configured via `config.toml` (LVM partitioning with 20GB
minimum, XFS root filesystem, default password `root:jumpstarter`).
### Build Kickstart ISO

To create a kickstart ISO that automates the installation:

```console
qemu-system-x86_64 \
-m 4096 \
-smp 2 \
-drive file=output/qcow2/disk.qcow2,format=qcow2 \
-net nic -net user,hostfwd=tcp::8880-:8880,hostfwd=tcp::443-:443
make download-centos-iso # Downloads CentOS Stream 10 ISO
make build-ks-iso # Creates kickstart ISO
```

### Network
For ARM64 builds:

The system uses `nip.io` for automatic DNS resolution (e.g.
`jumpstarter.10.0.2.2.nip.io`).
```console
make download-centos-iso ARCH=aarch64
make build-ks-iso ARCH=aarch64
```

| 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) |
### Development Workflow

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

1. **Default Password:** `root:jumpstarter`. Console login forces a change. Web
UI requires a change before access.
2. **TLS Certificates:** MicroShift uses self-signed certs by default.
3. **Privileged Container:** Required for systemd, LVM, and networking.
4. **Authentication:** Web UI uses PAM authentication with root credentials.
```console
make bootc-reload-app
```

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

## Troubleshooting
### Shell Access

### LVM/TopoLVM Issues
Open a shell in the running container:

```console
make bootc-sh
```

### Troubleshooting

#### LVM/TopoLVM Issues

```console
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
#### MicroShift Not Starting

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

### Configuration Service Issues
#### Configuration Service Issues

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

## Uninstall
### Cleanup

Stop and remove the container:

```console
make bootc-stop
make bootc-rm
```

Remove all build artifacts and images:

```console
make clean
```

`make bootc-rm` stops the container, cleans up LVM volume groups, and detaches
loop devices. `make clean` removes the LVM disk image.
### Customization

Override the default image tag:

```console
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

## Makefile Targets
Push single-architecture image:

| Target | Description |
|--------|-------------|
| `make bootc-build` | Build the bootc container image |
| `make bootc-run` | Run MicroShift in a container |
| `make bootc-stop` | Stop the running container |
| `make bootc-rm` | Remove container and clean up LVM resources |
| `make bootc-sh` | Open shell in container |
| `make bootc-reload-app` | Reload config service without rebuild |
| `make build-image` | Create bootable QCOW2 image |
| `make bootc-push` | Push image to registry |
| `make clean` | Clean up images, artifacts, and LVM disk |
```console
make bootc-push
```

Push multi-architecture manifest:

```console
make bootc-push-multi
```
Loading