From b628a6c119e1cf39c495d13afed1d9784ff43624 Mon Sep 17 00:00:00 2001 From: Max Roby Date: Mon, 9 Oct 2023 21:28:52 +0200 Subject: [PATCH] start adding QEMU --- docs/12-self-hosting/01-overview.mdx | 55 +- .../02-host-creation/01-overview.mdx | 19 + .../{01-bare-metal.mdx => 02-bare-metal.mdx} | 0 .../02-host-creation/02-multipass.mdx | 143 +++++ .../02-virtual-machines-basic.mdx | 142 ----- .../02-host-creation/03-qemu.mdx | 496 ++++++++++++++++++ .../01-debian-setup.mdx | 0 .../02-ubuntu-setup.mdx | 0 .../_category_.yaml | 0 docs/12-self-hosting/04-advanced-options.mdx | 16 - .../01-gitlab-pipelines.mdx | 3 +- .../02-github-actions.mdx | 3 +- .../_category_.yaml | 0 13 files changed, 680 insertions(+), 197 deletions(-) create mode 100644 docs/12-self-hosting/02-host-creation/01-overview.mdx rename docs/12-self-hosting/02-host-creation/{01-bare-metal.mdx => 02-bare-metal.mdx} (100%) create mode 100644 docs/12-self-hosting/02-host-creation/02-multipass.mdx delete mode 100644 docs/12-self-hosting/02-host-creation/02-virtual-machines-basic.mdx create mode 100644 docs/12-self-hosting/02-host-creation/03-qemu.mdx rename docs/12-self-hosting/{02-host-provisioning => 03-host-provisioning}/01-debian-setup.mdx (100%) rename docs/12-self-hosting/{02-host-provisioning => 03-host-provisioning}/02-ubuntu-setup.mdx (100%) rename docs/12-self-hosting/{02-host-provisioning => 03-host-provisioning}/_category_.yaml (100%) delete mode 100644 docs/12-self-hosting/04-advanced-options.mdx rename docs/12-self-hosting/{03-runner-application-installation => 04-runner-application-installation}/01-gitlab-pipelines.mdx (98%) rename docs/12-self-hosting/{03-runner-application-installation => 04-runner-application-installation}/02-github-actions.mdx (98%) rename docs/12-self-hosting/{03-runner-application-installation => 04-runner-application-installation}/_category_.yaml (100%) diff --git a/docs/12-self-hosting/01-overview.mdx b/docs/12-self-hosting/01-overview.mdx index 72a1526b..039d8aa8 100644 --- a/docs/12-self-hosting/01-overview.mdx +++ b/docs/12-self-hosting/01-overview.mdx @@ -43,32 +43,33 @@ This guide is tested on devics which meet the following requirements: :::info Support for GPU-acceleration within containerized environments is limited to Nvidia hardware only at this time. ::: -## Host Creation Methods +## Host Creation Guides -### 1. Bare-Metal (Easiest) +"Host Creation" in this context is the process for installing an operating system onto a piece of +physical (also called "Bare Metal") or virtualized hardware. Instructions for installation on OS on +a bare-metal host and guides for creating virtual machines can be found in the +[Host Creation](./02-host-creation/01-overview.mdx) directory. -"Bare Metal" means that your host OS is running directly on a piece of hardware without any -virtulization. This reduces the complexity of deploymnet at the cost of increased time and effort -for re-provisioning the host. The following guides will walk you through the installation process on -a bare-metal host. +## Host Provisioning Guides -- Install Ubuntu 22.04 on a local machine -- Install Debian 12 on a local machine +"Provisioning" here refers to the process of installing additional resources onto, and the +configuration of your host beyond installing the base operating-system. Once you can sign into your +VM or Bare-Metal host, follow the appropriate guide to complete the provisioning process. -### 2. Virtual Machines (Intermediate) +- [Ubuntu 22.04 Setup](./03-host-provisioning/02-ubuntu-setup.mdx) -Virtual Machines are a software-defined layer of abstraction atop a Bare-Metal host which makes -deployments more consistent and easier to manage declaratively. This greaty reduces the difficulty -of re-deployment and creates the conditions required for securely running multiple guests within the -same physical host. Virtual Machines can also be used to create hosts that run different operating -systems (Windows, MacOS) or architectures (ARM) than the host machines. This added functionality -comes at the cost of added complexity, a slight performance penalty, and you need to already have a -Bare-Metal host on which to run the VMs. +- [Debian 12 Setup](./03-host-provisioning/01-debian-setup.mdx) + +## Runner Application Installation -- Basic Virtual Machine creation with Multipass -- Advanced Virtual Machine creation with QEMU +Once your host has been provisioned, you will then need to install the appropriate runner +application. The guides below will walk you through that process. -### 3. Cloud-Init (Advanced) +- [Github Actions](./04-runner-application-installation/02-github-actions.mdx) + +- [GitLab Pipelines](./04-runner-application-installation/01-gitlab-pipelines.mdx) + +## Declarative workflow using Cloud-Init (Advanced) Cloud-Init is a software package that automates the initialization of cloud instances during system boot and has become the industry standard solution for operating system customization. Cloud-Init is @@ -80,19 +81,3 @@ bare-metal systems running Ubuntu. [PXEless](https://github.com/cloudymax/pxeless) - Using cloud-init with Multipass for automated provisioning - Use your cloud-init config to deploy VMs in the cloud - -## Host Provisioning Methods - -"Provisioning" here refers to the process of installing additional resources onto, and the -configuration of your host beyond installing the base operating-system. Once you can sign into your -VM or Bare-Metal host, follow the appropriate guide to complete the provisioning process. - -- [Ubuntu 22.04 Setup](./ubuntu-setup) - -- [Debian 12 Setup](./debian-setup) - -## Runner Application Installation - -- [Github Actions](./github-actions) - -- [GitLab Pipelines](./gitlab-pipelines) diff --git a/docs/12-self-hosting/02-host-creation/01-overview.mdx b/docs/12-self-hosting/02-host-creation/01-overview.mdx new file mode 100644 index 00000000..f65f8880 --- /dev/null +++ b/docs/12-self-hosting/02-host-creation/01-overview.mdx @@ -0,0 +1,19 @@ +# Overview + +## Types of Hosts + +1. Bare-Metal + +"Bare Metal" means that your host OS is running directly on a piece of hardware without any +virtulization. This reduces the complexity of deploymnet at the cost of increased time and effort +for re-provisioning the host. + +2. Virtual Machines + +Virtual Machines are a software-defined layer of abstraction atop a Bare-Metal host which makes +deployments more consistent and easier to manage declaratively. This greaty reduces the difficulty +of re-deployment and creates the conditions required for securely running multiple guests within the +same physical host. Virtual Machines can also be used to create hosts that run different operating +systems (Windows, MacOS) or architectures (ARM) than the host machine. This added functionality +comes at the cost of added complexity, a slight performance penalty, and you need to already have a +Bare-Metal host on which to run the VMs. diff --git a/docs/12-self-hosting/02-host-creation/01-bare-metal.mdx b/docs/12-self-hosting/02-host-creation/02-bare-metal.mdx similarity index 100% rename from docs/12-self-hosting/02-host-creation/01-bare-metal.mdx rename to docs/12-self-hosting/02-host-creation/02-bare-metal.mdx diff --git a/docs/12-self-hosting/02-host-creation/02-multipass.mdx b/docs/12-self-hosting/02-host-creation/02-multipass.mdx new file mode 100644 index 00000000..7c3b266a --- /dev/null +++ b/docs/12-self-hosting/02-host-creation/02-multipass.mdx @@ -0,0 +1,143 @@ +--- +toc_max_heading_level: 4 +--- + +# Multipass + +:::info Multipass only creates Ubuntu VMs ::: + +Multipass is a light-weight Virtual Machine Manager for Linux, Windows and MacOS. It's designed for +developers who want to quickly create a fresh Ubuntu environment with a single command. It uses the +native hypervisor for whichever platform it is installed on (KVM on Linux, Hyper-V on Windows and +HyperKit on MacOS) to run VMs with minimal overhead. It can also use VirtualBox on Windows and +MacOS. + +- [Official Webite](https://multipass.run/) +- [Official Github Repo](https://github.com/canonical/multipass) + +## installation + +To install multipass on Linux use the commands below. + +```bash +sudo apt-get install snapd +sudo snap install core +sudo snap install multipass +``` + +For installation on Windows and MacOS, refer to the official installation instructions: + +- [How to install Multipass on Windows](https://multipass.run/docs/installing-on-windows) +- [How to install Multipass on macOS](https://multipass.run/docs/installing-on-macos) + +## Creating a VM + +1. Set values + +```bash +# The name of the Virtual Machine +export VM_NAME="gameci" + +# The name of the user to create +export VM_USER="vmadmin" + +# Number of CPU cores to allocate to the VM +export VM_CPUS="2" + +# Amount of Disk Space to allocate to the VM. +# Cannot exceed available on host. +export VM_DISK="32G" + +# Amount of RAM to allocate to the VM. +# Cannot exceed available RAM on host. +export VM_MEM="8G" + +# Set path on MacOS systems +export PATH="$PATH:/usr/local/bin/multipass" + +# Set path on Linux system +export PATH="$PATH:/usr/local/bin/multipass" +``` + +2. Create an ssh-key for authenticating with the VM + +```bash +ssh-keygen -C $VM_USER -f runner +``` + +3. Add the public ssh-key to a cloud-init file + +See the [cloud init](https://cloudinit.readthedocs.io/en/latest/topics/examples.html) docs for more +examples. + +```bash +VM_KEY=$(cat runner.pub) + +cat << EOF > cloud-init.yaml +#cloud-config +groups: + - docker +users: + - default + - name: ${VM_USER} + sudo: ALL=(ALL) NOPASSWD:ALL + shell: /bin/bash + groups: docker, admin, sudo, users + no_ssh_fingerprints: true + ssh-authorized-keys: + - ${VM_KEY} +packages: + - docker.io +runcmd: + - [ sed , -i , "s/#PermitRootLogin prohibit-password/PermitRootLogin no/g" , /etc/ssh/sshd_config ] +EOF +``` + +4. Start the VM + +See the [multipass launch](https://multipass.run/docs/launch-command) command docs for more +information. + +```bash +export VERBOSITY="-vvvvvv" + +/snap/bin/multipass launch --name $VM_NAME \ + --cpus $VM_CPUS \ + --disk $VM_DISK \ + --mem $VM_MEM \ + --cloud-init cloud-init.yaml \ + $VERBOSITY +``` + +4. Get the VM's IP address + +```bash +VM_IP=$(/snap/bin/multipass list |grep "${VM_NAME}" |awk '{print $3}') +``` + +5. Connect to the VM via ssh or cli + +ssh: + +```bash +ssh -i runner $VM_USER@$VM_IP -o StrictHostKeyChecking=no -vvvv +``` + +CLI: + +```bash +multipass shell $VM_NAME +``` + +6. Install the runner application using one of the guides below: + + - [Github Actions](../04-runner-application-installation/02-github-actions.mdx) + - [Gitlab Pipelines](../04-runner-application-installation/01-gitlab-pipelines.mdx) + +7. Cleanup when finished + +```bash +/snap/bin/multipass stop $VM_NAME +/snap/bin/multipass delete $VM_NAME +/snap/bin/multipass purge +``` diff --git a/docs/12-self-hosting/02-host-creation/02-virtual-machines-basic.mdx b/docs/12-self-hosting/02-host-creation/02-virtual-machines-basic.mdx deleted file mode 100644 index 0020e832..00000000 --- a/docs/12-self-hosting/02-host-creation/02-virtual-machines-basic.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -toc_max_heading_level: 4 ---- - -# Creating a Virtual Machine - -You may find yourself with the requirement for multiple runners, runners of differing -configurations, or different operating systems but only have access to a single Host. In this case, -you can split your Host into multiple runners using virtualization. - -## Multipass - -Multipass is a lightweight VM manager for Linux, Windows and macOS. It's designed to provide a -cloud-like Ubuntu environment with a single command. It uses KVM on Linux, Hyper-V on Windows and -HyperKit on macOS to run the VM with minimal overhead. It can also use VirtualBox on Windows and -macOS. Multipass supports cloud-init and auto-install for vm configuration. - -- [multipass](https://multipass.run/) -- [github.com/canonical/multipass](https://github.com/canonical/multipass) -- [cloud-init](https://cloud-init.io/) - -### Install - -Windows: - -- https://multipass.run/docs/installing-on-windows -- https://multipass.run/docs/windows-tutorial - -MacOS: - -- https://multipass.run/docs/installing-on-macos -- https://multipass.run/docs/mac-tutorial - -Linux: - -- Install via apt + snap - - ```bash - sudo apt update - sudo apt install -y snapd - sudo snap install core - sudo snap install multipass - export PATH="$PATH:/snap/bin" - ``` - -### Create a VM on a Linux host - -- Set options - - ```bash - #program verbosity - export VERBOSITY="-vvvvv" - export DEBUG="true" - export SQUASH="false" - - # Virtual Machine Configuration - export VM_NAME="test" - export VM_IMAGE="jammy" - export VM_CPUS="4" - export VM_DISK="32G" - export VM_MEM="4G" - export VM_IP="none" - export VM_USER="max" - export VM_KEY="" - export VM_IP="" - export SSH_PORT="22" - - # temporary files - export VM_INIT="cloud-init.yaml" - export VM_KEY_FILE="$(pwd)/$VM_USER" - ``` - -- Create an ssh-key for the admin user - - ```bash - yes | ssh-keygen -C "$VM_USER" \ - -f "$VM_KEY_FILE" \ - -N '' \ - -t rsa -q - - VM_KEY=$(cat "$VM_KEY_FILE".pub) - ``` - -- Create the cloud-init config file: - - ```yaml - cat << EOF > ${VM_INIT} - #cloud-config - groups: - - docker - users: - - default - - name: ${VM_USER} - sudo: ALL=(ALL) NOPASSWD:ALL - shell: /bin/bash - groups: docker, admin, sudo, users - no_ssh_fingerprints: true - ssh-authorized-keys: - - ${VM_KEY} - packages: - - docker.io - - docker-compose - runcmd: - - [ sed , -i , "s/#Port 22/Port ${SSH_PORT}/g" , /etc/ssh/sshd_config ] - - [ sed , -i , "s/#PermitRootLogin prohibit-password/PermitRootLogin no/g" , /etc/ssh/sshd_config ] - EOF - ``` - -- Start the VM - - ```bash - multipass launch --name $VM_NAME \ - --cpus $VM_CPUS \ - --disk $VM_DISK \ - --mem $VM_MEM \ - $VM_IMAGE \ - --cloud-init $VM_INIT \ - --timeout 300 \ - $VERBOSITY - ``` - -- Get the ip address and ssh into the vm. - -SSH: - -```bash -export VM_IP=$(multipass info $VM_NAME | grep IPv4 |awk '{print $2}') -ssh -i $VM_KEY_FILE \ - $VM_USER@$VM_IP \ - -o StrictHostKeyChecking=no \ - -p $SSH_PORT \ - -t \ - /bin/bash -``` - -CLI: - -```bash -multipass shell runner -``` - -## QEMU/KVM diff --git a/docs/12-self-hosting/02-host-creation/03-qemu.mdx b/docs/12-self-hosting/02-host-creation/03-qemu.mdx new file mode 100644 index 00000000..19a4dfdc --- /dev/null +++ b/docs/12-self-hosting/02-host-creation/03-qemu.mdx @@ -0,0 +1,496 @@ +--- +toc_max_heading_level: 4 +--- + +# QEMU + +:::info This guide is for use with Debian12 and Ubuntu22.04 hosts only. ::: + +[QEMU](https://www.qemu.org/documentation/) is an open source machine emulator and virtualizer. It +can be used for **system emulation**, where it provides a virtual model of an entire machine to run +a guest OS or it may work with a another hypervisor like KVM or Xen. QEMU can also provide **user +mode emulation**, where QEMU can launch processes compiled for one CPU on another CPU via emulation. + +QEMU is special amongst its counterparts for a couple important reasons: + +- Like [ESXi](https://www.vmware.com/nl/products/esxi-and-esx.html), its capable of PCI passthrough + for GPUs + ([VirtualBox](https://docs.oracle.com/en/virtualization/virtualbox/6.0/user/guestadd-video.html) + cant help us here) +- Unlike ESXi, it's free +- When used with KVM, QEMU provides near-native levels of performance. +- Can be used inside Kubernetes via [Kubevirt](https://kubevirt.io/) +- It's fast. QEMU can create a new fully-featured VM in seconds. That's not quite as fast as + [LXD](https://linuxcontainers.org/lxd/introduction/), + [FireCracker](https://firecracker-microvm.github.io/), or + [Cloud-Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) (formerly + [NEMU](https://github.com/intel/nemu)), but its far more mature, featureful, and thoroughly + documented. +- Unlike a [system container (LDX)](https://linuxcontainers.org/lxd/introduction/) or + [Multipass](https://multipass.run/docs) it can also create Windows and MacOS guests. +- [Unlike Firecracker](https://github.com/firecracker-microvm/firecracker/issues/849#issuecomment-464731628) + it supports pinning memmory addresses (and thus PCIe-passthrough) where firecracker cannot because + it would break their core feature of over-subscription. + +These qualities make QEMU well-suited for those seeking a highly-performant ad fully-featured +hypervisor. + +## Requirements + +- Linux host running Debian12 or Ubuntu 22.04 +- VNC viewer software installed on the machien you will use to access the VM + - [TightVNC](https://www.tightvnc.com/download.php) (Windows) + - [Remina](https://remmina.org/) (Linux) + - [RealVNC](https://www.realvnc.com/en/connect/download/viewer/macos/) or + [TigerVNC](https://sourceforge.net/projects/tigervnc/files/stable/1.13.1/TigerVNC-1.13.1.dmg/download) + (MacOS) + +## Setup + +- Install QEMU and its dependancies + + ```bash + sudo apt-get install -y qemu-kvm \ + bridge-utils \ + virtinst\ + ovmf \ + qemu-utils \ + cloud-image-utils \ + tmux \ + whois \ + git \ + jq \ + git-extras \ + guestfs-tools \ + bridge-utils + ``` + +## Configure the Virtual Machine options + +```bash +# The name of the Virtual Machine +export VM_NAME="gameci" + +# The name of the user to create +export VM_USER="vmadmin" + +# Number of physical CPU cores to allocate to the VM +export PHYSICAL_CORES="2" + +# Number of threads per core. +# Set this to `1` for CPUs that do not support hyperthrading +export THREADS="1" +export SMP=$(( $PHYSICAL_CORES * $THREADS )) + +# Amount of Disk Space to allocate to the VM. +# Cannot exceed available on host. +export DISK_SIZE="32G" + +# Amount of RAM to allocate to the VM. +# Cannot exceed available RAM on host. +export MEMORY="8G" + +# IP address where host may be reached. Do not use `localhost`. +export HOST_ADDRESS="SOME IP HERE" + +# Port used by SSH on the host +export HOST_SSH_PORT="22" + +# Port to use when forwarding SSH to the VM +export VM_SSH_PORT="1234" + +# Port number to expose on the host for VNC +export VNC_PORT="0" +``` + +### Linux Guest (Cloud Image) + +"Cloud-Images" are lightweight (usually under 700Mb) snapshots of a configured OS created by a +publisher for use with public and private clouds. These images provide a way to repeatably create +identical copies of a machine across platforms. We will use cloud-init to customize the cloud-image +immediately upon booting, prior to user-space initialization. + +1. Create an SSH Key + +```bash +yes |ssh-keygen -C "$VM_USER" \ + -f runner \ + -N '' \ + -t rsa +``` + +2. Create a password + +```bash +# Install the mkpasswd utility +sudo apt install -y whois + +read PW_STRING +export PASSWORD=$(mkpasswd -m sha-512 --rounds=4096 "$PW_STRING" -s "saltsaltlettuce") +``` + +3. Create a cloud-init file + +```bash +VM_KEY=$(cat runner.pub) + +/bin/cat << EOF > cloud-init.yaml +#cloud-config +hostname: runner +disable_root: false +network: + config: disabled +users: + - name: ${VM_USER} + groups: users, admin, sudo + sudo: ALL=(ALL) NOPASSWD:ALL + shell: /bin/bash + lock_passwd: false + passwd: ${PASSWORD} + ssh_authorized_keys: + - ${VM_KEY} +EOF +``` + +4. Create a cloud-init disk + +```bash +cloud-localds seed.img cloud-init.yaml +``` + +5. Choose a cloud-image to use as the base OS: + +```yaml +Debian: + 12: 'https://laotzu.ftp.acc.umu.se/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2' +Ubuntu: + focal: 'https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.img' + jammy: 'https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img' + lunar: 'https://cloud-images.ubuntu.com/lunar/current/lunar-server-cloudimg-amd64.img' +``` + +6. Download the image with `wget` + +```bash +export CLOUD_IMAGE_URL="https://laotzu.ftp.acc.umu.se/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2" +export CLOUD_IMAGE_NAME=$(basename -- "$CLOUD_IMAGE_URL") +wget -c -O "$CLOUD_IMAGE_NAME" "$CLOUD_IMAGE_URL" -q --show-progress +``` + +7. Create a virtual disk using the cloud-image as a read-only backing file. + +```bash +qemu-img create -b ${CLOUD_IMAGE_NAME} -f qcow2 \ + -F qcow2 disk.qcow2 \ + "$DISK_SIZE" 1> /dev/null +``` + +8. Create new guest: + +```bash +sudo qemu-system-x86_64 \ + -machine accel=kvm,type=q35 \ + -cpu host \ + -smp $SMP,sockets=1,cores="$PHYSICAL_CORES",threads="$THREADS",maxcpus=$SMP \ + -m "$MEMORY" \ + -serial stdio -vga virtio -parallel none \ + -device virtio-net-pci,netdev=network \ + -netdev user,id=network,hostfwd=tcp::"${VM_SSH_PORT}"-:"${HOST_SSH_PORT}" \ + -object iothread,id=io \ + -device virtio-blk-pci,drive=disk,iothread=io \ + -drive if=none,id=disk,cache=none,format=qcow2,aio=threads,file=disk.qcow2 \ + -drive if=virtio,format=raw,file=seed.img,index=0,media=disk \ + -bios /usr/share/ovmf/OVMF.fd \ + -usbdevice tablet \ + -vnc $HOST_ADDRESS:$VNC_PORT +``` + +or Boot an existing guest: + +```bash +sudo qemu-system-x86_64 \ + -machine accel=kvm,type=q35 \ + -cpu host \ + -smp $SMP,sockets=1,cores="$PHYSICAL_CORES",threads="$THREADS",maxcpus=$SMP \ + -m "$MEMORY" \ + -serial stdio -vga virtio -parallel none \ + -device virtio-net-pci,netdev=network \ + -netdev user,id=network,hostfwd=tcp::"${VM_SSH_PORT}"-:"${HOST_SSH_PORT}" \ + -object iothread,id=io \ + -device virtio-blk-pci,drive=disk,iothread=io \ + -drive if=none,id=disk,cache=none,format=qcow2,aio=threads,file=disk.qcow2 \ + -bios /usr/share/ovmf/OVMF.fd \ + -usbdevice tablet \ + -vnc $HOST_ADDRESS:$VNC_PORT +``` + +9. Connect to VM over SSH + +- Copy the ssh private key `runner` to the machine you wish to connect to the VM with. +- Connect to the vm using the format `ssh -i runner $VM_USER@$HOST_ADDRESS -p$VM_SSH_PORT` + +10. Connect tot he VM using VNC + +- In your VNC software use the address format `$HOST_ADDRESS:$VNC_PORT` to connect to the VM. + +### Linux Guest (Live-ISO) + +Live-ISO installers usually contain the full set of requirements for installing a operating system +as well as extra content for optional features. These images are much heavier than cloud-images and +are generally 2-8Gb in size. Unlike cloud-images, Live-ISO installers can also be used to image +phyiscal machines. + +1. Choose an ISO file: + +```yaml +Ubuntu: + - https://mirror.mijn.host/ubuntu-releases/22.04.3/ubuntu-22.04.3-live-server-amd64.iso +Debian12: + - https://cdimage.debian.org/debian-cd/current/amd64/iso-dvd/debian-12.1.0-amd64-DVD-1.iso +``` + +> When using Debian12 as the source image, you may need to manually add a boot-entry to the +> virtual-machine bios after installation. That process is shown in-detail here: +> [proxmox.com/wiki/OVMF/UEFI_Boot_Entries](https://pve.proxmox.com/wiki/OVMF/UEFI_Boot_Entries) + +2. Download the installer + +```bash +export IMAGE_URL="https://cdimage.debian.org/debian-cd/current/amd64/iso-dvd/debian-12.1.0-amd64-DVD-1.iso" +export IMAGE_NAME=$(basename -- "$IMAGE_URL") +wget -c -O "$IMAGE_NAME" "$IMAGE_URL" -q --show-progress +``` + +3. Create an empty disk where the OS will be installed. + +```bash +qemu-img create -f qcow2 disk.qcow2 $DISK_SIZE &>/dev/null +``` + +4. Create a new guest: + +```bash +sudo qemu-system-x86_64 \ + -machine accel=kvm,type=q35 \ + -cpu host,kvm="off",hv_vendor_id="null" \ + -smp $SMP,sockets=1,cores="$PHYSICAL_CORES",threads="$THREADS",maxcpus=$SMP \ + -m "$MEMORY" \ + -cdrom $IMAGE_NAME \ + -object iothread,id=io \ + -device virtio-blk-pci,drive=disk,iothread=io \ + -drive if=none,id=disk,cache=none,format=qcow2,aio=threads,file=disk.qcow2 \ + -device intel-hda \ + -device hda-duplex \ + -serial stdio -vga virtio -parallel none \ + -device virtio-net-pci,netdev=network \ + -netdev user,id=network,hostfwd=tcp::"${VM_SSH_PORT}"-:"${HOST_SSH_PORT}" \ + -bios /usr/share/ovmf/OVMF.fd \ + -usbdevice tablet \ + -vnc $HOST_ADDRESS:$VNC_PORT +``` + +or boot existing guest: + +```bash +sudo qemu-system-x86_64 \ + -machine accel=kvm,type=q35 \ + -cpu host,kvm="off",hv_vendor_id="null" \ + -smp $SMP,sockets=1,cores="$PHYSICAL_CORES",threads="$THREADS",maxcpus=$SMP \ + -m "$MEMORY" \ + -object iothread,id=io \ + -device virtio-blk-pci,drive=disk,iothread=io \ + -drive if=none,id=disk,cache=none,format=qcow2,aio=threads,file=disk.qcow2 \ + -device intel-hda \ + -device hda-duplex \ + -serial stdio -vga virtio -parallel none \ + -device virtio-net-pci,netdev=network \ + -netdev user,id=network,hostfwd=tcp::"${VM_SSH_PORT}"-:"${HOST_SSH_PORT}" \ + -bios /usr/share/ovmf/OVMF.fd \ + -usbdevice tablet \ + -vnc $HOST_ADDRESS:$VNC_PORT +``` + +9. Connect to VM over SSH + +- Copy the ssh private key `runner` to the machine you wish to connect to the VM with. +- Connect to the vm using the format `ssh -i runner $VM_USER@$HOST_ADDRESS -p$VM_SSH_PORT` + +10. Connect tot he VM using VNC + +- In your VNC software use the address format `$HOST_ADDRESS:$VNC_PORT` to connect to the VM. + +### Windows Guest + +1. Select a Windows ISO + +```yaml +Windows: + Windows10: 'https://www.itechtics.com/?dl_id=173' + server2019-core: 'https://go.microsoft.com/fwlink/p/?LinkID=2195167&clcid=0x409&culture=en-us&country=US' + Tiny10: https://ia902609.us.archive.org/27/items/tiny-10-NTDEV/tiny10%2023h1%20x64.iso + Tiny11: https://ia800509.us.archive.org/27/items/tiny11-23h2/tiny11%2023H2%20x64.iso +``` + +2. Donwload installer + +```bash +export IMAGE_URL="https://www.itechtics.com/?dl_id=173" +export IMAGE_NAME=windows.iso +wget -c -O "$IMAGE_NAME" "$IMAGE_URL" -q --show-progress +``` + +3. Download virtual-disk drivers + +```bash +wget -O "virtio-drivers.iso" "https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/archive-virtio/virtio-win-0.1.240-1/virtio-win-0.1.240.iso" +``` + +4. Create the virtual disk + +```bash +qemu-img create -f qcow2 disk.qcow2 $DISK_SIZE &>/dev/null +``` + +5. Create new guest: + +```bash +sudo qemu-system-x86_64 \ + -machine accel=kvm,type=q35 \ + -cpu host,kvm="off",hv_vendor_id="null" \ + -smp $SMP,sockets=1,cores="$PHYSICAL_CORES",threads="$THREADS",maxcpus=$SMP \ + -m "$MEMORY" \ + -drive id=disk0,if=virtio,cache=none,format=qcow2,file=disk.qcow2 \ + -drive file=windows.iso,index=1,media=cdrom \ + -drive file=virtio-drivers.iso,index=2,media=cdrom \ + -boot menu=on \ + -bios /usr/share/ovmf/OVMF.fd \ + -usbdevice tablet \ + -serial stdio -vga virtio -parallel none \ + -device virtio-net-pci,netdev=network \ + -netdev user,id=network,hostfwd=tcp::"${VM_SSH_PORT}"-:"${HOST_SSH_PORT}" \ + -vnc $HOST_ADDRESS:$VNC_PORT +``` + +boot existing guest: + +```bash +sudo qemu-system-x86_64 \ + -machine accel=kvm,type=q35 \ + -cpu host,kvm="off",hv_vendor_id="null",check="off",hypervisor="off" \ + -smp $SMP,sockets=1,cores="$PHYSICAL_CORES",threads="$THREADS",maxcpus=$SMP \ + -m "$MEMORY" \ + -object iothread,id=io \ + -device virtio-blk-pci,drive=disk,iothread=io \ + -drive if=none,id=disk,cache=none,format=qcow2,aio=threads,file=disk.qcow2 \ + -drive file=Win10.iso,index=1,media=cdrom \ + -drive file=virtio-win-0.1.215.iso,index=2,media=cdrom \ + -boot menu=on \ + -serial none \ + -parallel none \ + -bios /usr/share/ovmf/OVMF.fd \ + -usbdevice tablet \ + -serial stdio -vga virtio -parallel none \ + -device virtio-net-pci,netdev=network \ + -netdev user,id=network,hostfwd=tcp::"${VM_SSH_PORT}"-:"${HOST_SSH_PORT}" \ + -vnc $HOST_ADDRESS:$VNC_PORT +``` + +### MacOS Guest + +MacOS guests utilize the open-source project https://github.com/kholia/OSX-KVM. + +1. Clone the repo and cd into the new directory + +```bash +git clone --depth 1 --recursive https://github.com/kholia/OSX-KVM.git +cd OSX-KVM +``` + +2. Choose and download an installer using the included script + +```bash +./fetch-macOS-v2.py +# 1. High Sierra (10.13) +# 2. Mojave (10.14) +# 3. Catalina (10.15) +# 4. Big Sur (11.7) +# 5. Monterey (12.6) +# 6. Ventura (13) - RECOMMENDED +# 7. Sonoma (14) +# Choose a product to download (1-6): 6 +``` + +3. Convert the downloaded BaseSystem.dmg file into the BaseSystem.img file. + +```bash +sudo apt-get install -y dmg2img && \ +dmg2img -i BaseSystem.dmg BaseSystem.img +``` + +4. Create a virtual disk image where MacOS will be installed. + +```bash +qemu-img create -f qcow2 mac_hdd_ng.img $DISK_SIZE &>/dev/null +``` + +5. Create new guest: + +```bash +sudo qemu-system-x86_64 \ + -machine accel=kvm,type=q35 \ + -cpu Penryn,kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on,+ssse3,+sse4.2,+popcnt,+avx,+aes,+xsave,+xsaveopt,check \ + -smp $SMP,sockets=1,cores="$PHYSICAL_CORES",threads="$THREADS",maxcpus=$SMP \ + -m "$MEMORY" \ + -device usb-ehci,id=ehci \ + -device nec-usb-xhci,id=xhci \ + -global nec-usb-xhci.msi=off \ + -device isa-applesmc,osk="ourhardworkbythesewordsguardedpleasedontsteal(c)AppleComputerInc" \ + -drive if=pflash,format=raw,readonly=on,file="OVMF_CODE.fd" \ + -drive if=pflash,format=raw,file="OVMF_VARS-1024x768.fd" \ + -smbios type=2 \ + -device ich9-intel-hda -device hda-duplex \ + -device ich9-ahci,id=sata \ + -drive id=OpenCoreBoot,if=none,snapshot=on,format=qcow2,file="OpenCore/OpenCore.qcow2" \ + -device ide-hd,bus=sata.2,drive="OpenCoreBoot" \ + -device ide-hd,bus=sata.3,drive="InstallMedia" \ + -drive id=InstallMedia,if=none,file="BaseSystem.img",format=raw \ + -object iothread,id=io \ + -device virtio-blk-pci,drive=MacHDD,iothread=io \ + -drive id=MacHDD,if=none,cache=none,format=qcow2,aio=threads,file="mac_hdd_ng.img" \ + -serial stdio -vga virtio -parallel none \ + -device virtio-net-pci,netdev=network \ + -usbdevice tablet \ + -device usb-kbd,bus=ehci.0 \ + -netdev user,id=network,hostfwd=tcp::"${VM_SSH_PORT}"-:"${HOST_SSH_PORT}" \ + -vnc $HOST_ADDRESS:$VNC_PORT +``` + +Boot existing guest: + +```bash +sudo qemu-system-x86_64 \ + -machine accel=kvm,type=q35 \ + -cpu Penryn,kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on,+ssse3,+sse4.2,+popcnt,+avx,+aes,+xsave,+xsaveopt,check \ + -smp $SMP,sockets=1,cores="$PHYSICAL_CORES",threads="$THREADS",maxcpus=$SMP \ + -m "$MEMORY" \ + -device usb-ehci,id=ehci \ + -device nec-usb-xhci,id=xhci \ + -global nec-usb-xhci.msi=off \ + -device isa-applesmc,osk="ourhardworkbythesewordsguardedpleasedontsteal(c)AppleComputerInc" \ + -drive if=pflash,format=raw,readonly=on,file="OVMF_CODE.fd" \ + -drive if=pflash,format=raw,file="OVMF_VARS-1024x768.fd" \ + -smbios type=2 \ + -device ich9-intel-hda -device hda-duplex \ + -device ich9-ahci,id=sata \ + -drive id=OpenCoreBoot,if=none,snapshot=on,format=qcow2,file="OpenCore/OpenCore.qcow2" \ + -device ide-hd,bus=sata.2,drive="OpenCoreBoot" \ + -object iothread,id=io \ + -device virtio-blk-pci,drive=MacHDD,iothread=io \ + -drive id=MacHDD,if=none,cache=none,format=qcow2,aio=threads,file="mac_hdd_ng.img" \ + -serial stdio -vga virtio -parallel none \ + -device virtio-net-pci,netdev=network \ + -usbdevice tablet \ + -device usb-kbd,bus=ehci.0 \ + -netdev user,id=network,hostfwd=tcp::"${VM_SSH_PORT}"-:"${HOST_SSH_PORT}" \ + -vnc $HOST_ADDRESS:$VNC_PORT +``` diff --git a/docs/12-self-hosting/02-host-provisioning/01-debian-setup.mdx b/docs/12-self-hosting/03-host-provisioning/01-debian-setup.mdx similarity index 100% rename from docs/12-self-hosting/02-host-provisioning/01-debian-setup.mdx rename to docs/12-self-hosting/03-host-provisioning/01-debian-setup.mdx diff --git a/docs/12-self-hosting/02-host-provisioning/02-ubuntu-setup.mdx b/docs/12-self-hosting/03-host-provisioning/02-ubuntu-setup.mdx similarity index 100% rename from docs/12-self-hosting/02-host-provisioning/02-ubuntu-setup.mdx rename to docs/12-self-hosting/03-host-provisioning/02-ubuntu-setup.mdx diff --git a/docs/12-self-hosting/02-host-provisioning/_category_.yaml b/docs/12-self-hosting/03-host-provisioning/_category_.yaml similarity index 100% rename from docs/12-self-hosting/02-host-provisioning/_category_.yaml rename to docs/12-self-hosting/03-host-provisioning/_category_.yaml diff --git a/docs/12-self-hosting/04-advanced-options.mdx b/docs/12-self-hosting/04-advanced-options.mdx deleted file mode 100644 index 4c0f5b58..00000000 --- a/docs/12-self-hosting/04-advanced-options.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -toc_max_heading_level: 4 ---- - -# Advanced Topics - -## Cloud Instances - -## Virtual Machines - -You may find yourself with the requirement for multiple runners, runners of differing -configurations, or different operating systems but only have access to a single Host. In this case, -you can split your Host into multiple runners using virtualization. If this applies to you, complete -the provisioning step and then follow the [Virtual Machines Guide](./virtual-machines). - -## Kubenertes diff --git a/docs/12-self-hosting/03-runner-application-installation/01-gitlab-pipelines.mdx b/docs/12-self-hosting/04-runner-application-installation/01-gitlab-pipelines.mdx similarity index 98% rename from docs/12-self-hosting/03-runner-application-installation/01-gitlab-pipelines.mdx rename to docs/12-self-hosting/04-runner-application-installation/01-gitlab-pipelines.mdx index ad0362b9..49f8802a 100644 --- a/docs/12-self-hosting/03-runner-application-installation/01-gitlab-pipelines.mdx +++ b/docs/12-self-hosting/04-runner-application-installation/01-gitlab-pipelines.mdx @@ -179,8 +179,7 @@ see the following resources:

-8. Copy and paste the following int your terminal to create the script, or download it from (link - here TODO) +8. Copy and paste the following into your terminal to create the script ```bash /usr/bin/cat << 'EOF' > runner.sh diff --git a/docs/12-self-hosting/03-runner-application-installation/02-github-actions.mdx b/docs/12-self-hosting/04-runner-application-installation/02-github-actions.mdx similarity index 98% rename from docs/12-self-hosting/03-runner-application-installation/02-github-actions.mdx rename to docs/12-self-hosting/04-runner-application-installation/02-github-actions.mdx index bfbf6583..40c073ae 100644 --- a/docs/12-self-hosting/03-runner-application-installation/02-github-actions.mdx +++ b/docs/12-self-hosting/04-runner-application-installation/02-github-actions.mdx @@ -75,8 +75,7 @@ The following script will perform the same actions as described above automatica for those who would prefer ephemeral runners or to use a declarative workflow. You will need to provide your own access-token to the script as an input value. -1. Copy and paste the following int your terminal to create the script, or download it from (link - here TODO) +1. Copy and paste the following int your terminal to create the script ```bash /usr/bin/cat << 'EOF' > runner.sh diff --git a/docs/12-self-hosting/03-runner-application-installation/_category_.yaml b/docs/12-self-hosting/04-runner-application-installation/_category_.yaml similarity index 100% rename from docs/12-self-hosting/03-runner-application-installation/_category_.yaml rename to docs/12-self-hosting/04-runner-application-installation/_category_.yaml