diff --git a/python/docs/source/getting-started/installation/service/standalone.md b/python/docs/source/getting-started/installation/service/standalone.md index 2b79cdc79..21ef80cc6 100644 --- a/python/docs/source/getting-started/installation/service/standalone.md +++ b/python/docs/source/getting-started/installation/service/standalone.md @@ -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 +``` + +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) | + +### 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..nip.io:6443` - **Pod Monitoring**: `http://localhost:8880/pods` @@ -57,57 +112,65 @@ 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 @@ -115,41 +178,56 @@ 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 +```