Skip to content

Commit cd8711e

Browse files
cloudymaxdavidmfinolMax RobyGabLeRoux
authored
Add self-hosting documentation (#419)
* Update README.md * Add files via upload * remove extra line break * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * fix formatting * change link format from html to markdown * missed a link * Run prettier * run prettier with yarn instead of npx? * fix codeblock formatting * run prettier formatting * adding self-hosting docs * revise language based on feedback, add instructions for runner application installation * start adding QEMU * add images to vm setup docs, separate out qemu types * add new qemu dir * finish up Windows and add macos * run prettier on readme * add images to windows, cleanup formatting, fix spelling errors * change organasation structure and fix typos * re-roganize, add cloud-init details, dogfood testing * Fix spellign errors, dogfooding, add advanced qemu config guides * testing some style stuff that the linter doesnt like * testing some style stuff that the linter doesnt like * changing the syle to abuse titles less * changing the syle to abuse titles less * changing the syle to abuse titles less * changing the syle to abuse titles less * changing the syle to abuse titles less * cleanup dangling : * Formatting pass, add new diagrams * center images and lint * proof-reading and docgfood pass on k8s docs * add info on creating secrets, minor formatting * move k8s to new branch to unblock the rest of the docs * re-center images * add paddig above ssh image * change image indent so linter wont wreck the spacing * remove text artifact inserted by linter * center images * add disclaimers to advanced configs, add more examples to windows * remove text artifact introduced by linter and minor formatting fix * add missing image file * Update docs/12-self-hosting/01-overview.mdx Co-authored-by: Gabriel Le Breton <lebreton.gabriel@gmail.com> * Update docs/12-self-hosting/03-host-creation/03-QEMU/01-overview.mdx Co-authored-by: Gabriel Le Breton <lebreton.gabriel@gmail.com> * Update docs/12-self-hosting/03-host-creation/03-QEMU/01-overview.mdx Co-authored-by: Gabriel Le Breton <lebreton.gabriel@gmail.com> * Update docs/12-self-hosting/03-host-creation/03-QEMU/03-linux-liveiso.mdx Co-authored-by: Gabriel Le Breton <lebreton.gabriel@gmail.com> * fix issue with metal diagram failing to render as a svg, its a png now * remove accidental file addition * fix formatting * Update docs/12-self-hosting/03-host-creation/03-QEMU/03-linux-liveiso.mdx Co-authored-by: Gabriel Le Breton <lebreton.gabriel@gmail.com> * add power usage blurb * add doublequotes to VNC invocation * add sections to overview * add not on hackintosh legality * add note about remote access security to MacOS * fix typo in link * fix linux path for multipass --------- Co-authored-by: David Finol <davidmfinol@gmail.com> Co-authored-by: Max Roby <max@lil-mac.lan> Co-authored-by: Gabriel Le Breton <lebreton.gabriel@gmail.com>
1 parent 4747e1c commit cd8711e

File tree

88 files changed

+3225
-590
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

88 files changed

+3225
-590
lines changed

‎docs/12-self-hosting/01-overview.mdx‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
toc_max_heading_level: 4
3+
---
4+
5+
# About Self-Hosting
6+
7+
Projects often encounter a constraint or requirement which makes free-tier hosted CI/CD runners
8+
insufficient for their needs. In these cases hosting your own CI/CD runner can be a viable
9+
alternative to premium-tier services or subscriptions. Self-hosting may also provide access to
10+
resources that are simply not available on many CI/CD services such as GPUs, faster drives, and
11+
newer CPU models.
12+
13+
This guide will cover basic methods for hosting CI/CD runners on Bare-Metal, Virtual Machines, or
14+
using Cloud Runner. Containerized hosts will not be discussed because of their inherent reliance on
15+
insecure practices such as
16+
[Docker-in-Docker](http://jpetazzo.github.io/2015/09/03/do-not-use-docker-in-docker-for-ci/),
17+
[Privileged Containers](https://www.trendmicro.com/en_th/research/19/l/why-running-a-privileged-container-in-docker-is-a-bad-idea.html)
18+
and the additional tooling required to mitigate those risks such as
19+
[Kaniko](https://github.com/GoogleContainerTools/kaniko) or
20+
[Kata Containers](https://katacontainers.io/).
21+
22+
## 📚 Prerequisite Knowledge
23+
24+
Users of this guide should already be familiar with the Linux command-line, Shell scripting, and
25+
have a basic grasp of CI/CD concepts. For users who are not familiar with these concepts, we have
26+
included some resources for you to start your learning journey below.
27+
28+
- [Techworld with Nana](https://www.youtube.com/@TechWorldwithNana)
29+
- [DevOps Toolkit](https://www.youtube.com/@DevOpsToolkit)
30+
- [Introduction to Bash Scripting](https://itsfoss.com/bash-scripting-tutorial/)
31+
32+
## 📋 Constraints
33+
34+
There are many ways to self-host CI/CD runners, and which one is best for you will depend on your
35+
own situation and constraints. For the purpose of this guide we will make the following assumptions:
36+
37+
- 💻 User already has their own hardware
38+
- 💸 Budget for new hardware, software, or services is $0
39+
- 🛠️ FOSS tools should be prioritized where possible
40+
- 📜 We define `Self-Hosting` in this context to refer to a user taking responsibility for the
41+
operating-system level configuration and life-cycle-management of a given compute resource (metal,
42+
on-prem, cloud VM, VPS etc...)
43+
44+
## ⚠️ Security Disclaimer
45+
46+
This guide strives to maintain a balance between convenience and security for the sake of usability.
47+
The examples included in this guide are intended for use with on-prem hardware without public IP
48+
addresses accessible from external networks. Security is a constantly moving target which requires
49+
continuous effort to maintain. Users should conduct their own security review before using the
50+
following techniques on production or public systems.
51+
52+
## ⚡️ Power Costs
53+
54+
Hosting your own runners also comes with an increase in power consumption. This will vary based on
55+
the hardware you use and the prices of energy in your area. Below are some useful resources for
56+
discovering the potential energy costs of self-hosting.
57+
58+
- https://outervision.com/power-supply-calculator
59+
- https://energyusecalculator.com/electricity_computer.htm
60+
61+
## 💻 System Requirements
62+
63+
This guide is tested on devices which meet the following requirements:
64+
65+
- x86 or amd64 processor
66+
- Ubuntu 22.04 LTS Server or Debian 12 Bookworm
67+
- Root access to the operating system
68+
- Network connectivity
69+
70+
## 📎 Quick Links:
71+
72+
### Host Creation
73+
74+
"Host Creation" in this context is the process of installing an operating system onto a piece of
75+
physical hardware, or the creation and configuration of virtualised compute resources.
76+
77+
- [Bare-Metal](./03-host-creation/02-bare-metal.mdx)
78+
- [Virtual Machines using Multipass](./03-host-creation/02-multipass.mdx)
79+
- [Virtual Machines using QEMU](./03-host-creation/03-QEMU/01-overview.mdx)
80+
81+
### Host Provisioning
82+
83+
"Provisioning" here refers to the process of installing additional resources onto, and the
84+
configuration of your host beyond installing the base operating-system. Both manual and declarative
85+
workflows are supported.
86+
87+
- [Manual Ubuntu 22.04 Setup](./04-host-provisioning/02-ubuntu-setup.mdx)
88+
- [Manual Debian 12 Setup](./04-host-provisioning/01-debian-setup.mdx)
89+
- [Declarative provisioning via Cloud-Init](./04-host-provisioning/03-cloud-init/01-about.mdx)
90+
91+
### Runner Application Installation
92+
93+
Once your host has been provisioned, you will then need to install the appropriate runner
94+
application. The guides below will walk you through that process.
95+
96+
- [Github Actions](./05-runner-application-installation/02-github-actions.mdx)
97+
- [GitLab Pipelines](./05-runner-application-installation/01-gitlab-pipelines.mdx)

‎docs/12-self-hosting/02-host-types.mdx‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
import Virtualisation from '/assets/images/Virtualization.drawio.png';
2+
import Metal from '/assets/images/Metal.drawio.png';
3+
import Docker from '/assets/images/DockerHost.drawio.png';
4+
import Kubernetes from '/assets/images/kubernetes.drawio.png';
5+
import Layers from '/assets/images/k8s-layers.drawio.png';
6+
import Layer0 from '/assets/images/k8s-layer0.drawio.png';
7+
import Layer1 from '/assets/images/k8s-layer1.drawio.png';
8+
import Layer2 from '/assets/images/k8s-layer2.drawio.png';
9+
import Layers01 from '/assets/images/k8s-layers01.drawio.png';
10+
import Layers012 from '/assets/images/k8s-layers012.drawio.png';
11+
12+
# Types of Hosts
13+
14+
## Bare-Metal
15+
16+
"Bare Metal" means that your host OS is running directly on a piece of hardware without any
17+
virtualisation. This reduces the complexity of deployment at the cost of increased time and effort
18+
for re-provisioning the host.
19+
20+
<div style={{ textAlign: 'center' }}>
21+
<a target="\_blank" href={require('/assets/images/Metal.drawio.png').default}>
22+
<img src={Metal} width="500" />
23+
</a>
24+
</div>
25+
<br />
26+
27+
## Virtual Machines
28+
29+
Virtual Machines are a software-defined layer of abstraction atop a Bare-Metal host which makes
30+
deployments more consistent and easier to manage declaratively. This greatly reduces the difficulty
31+
of re-deployment and creates the conditions required for securely running multiple guests within the
32+
same physical host. Virtual Machines can also be used to create hosts that run different operating
33+
systems (Windows, MacOS) or architectures (ARM) than the host machine. This added functionality
34+
comes at the cost of added complexity, a slight performance penalty, and you need to already have a
35+
Bare-Metal host on which to run the VMs.
36+
37+
<div style={{ textAlign: 'center' }}>
38+
<a target="\_blank" href={require('/assets/images/Virtualization.drawio.png').default}>
39+
<img src={Virtualisation} width="500" />
40+
</a>
41+
</div>
42+
<br />
43+
44+
Additional Reading:
45+
46+
- [A Study of Performance and Security Across the Virtualization Spectrum](https://repository.tudelft.nl/islandora/object/uuid:34b3732e-2960-4374-94a2-1c1b3f3c4bd5/datastream/OBJ/download) -
47+
Vincent van Rijn
48+
- [Hyper-converged infrastructure](https://en.wikipedia.org/wiki/Hyper-converged_infrastructure) -
49+
Wikipedia
50+
- [Rethinking the PC](https://www.computerworld.com/article/3518849/rethinking-the-pc-why-virtual-machines-should-replace-operating-systems.html) -
51+
Rob Enderle
52+
53+
## Containers
54+
55+
Containers are built on 'cgroups' (control groups), which are a feature of the Linux kernel that
56+
limits monitors, and isolates the resource usage of a collection of processes. This means that
57+
running containers on Linux is very lightweight form of virtualisation. However, on other operating
58+
systems which do not use the Linux kernel, a Linux virtual machine or translation-layer must be
59+
created to run containers. The manner by which each Operating System resolves this issue varies
60+
greatly as shown below. Because of this variance, the self-hosting documentation targets Linux as a
61+
means of avoiding excess complexity.
62+
63+
<div style={{ textAlign: 'center' }}>
64+
<a target="\_blank" href={require('/assets/images/DockerHost.drawio.png').default}>
65+
<img src={Docker} width="500" />
66+
</a>
67+
</div>
68+
<br />
69+
70+
Additional Reading:
71+
72+
- [The Mental Model Of Docker Container Shipping](https://bernhardwenzel.com/2022/the-mental-model-of-docker-container-shipping/) -
73+
Bernhard Wenzel
74+
- [Why is Docker-in-Docker considered bad?](https://devops.stackexchange.com/questions/676/why-is-docker-in-docker-considered-bad)
75+
- [Why it is recommended to run only one process in a container?](https://devops.stackexchange.com/questions/447/why-it-is-recommended-to-run-only-one-process-in-a-container)
76+
77+
## Kubernetes (Cloud Runner)
78+
79+
Kubernetes is somewhat of a combination of all other host types. Since it is an API, it must be
80+
installed on an existing host (called a "Node") which is usually either a VM or physical device. A
81+
Kubernetes "Cluster" is usually made up of 3 or more nodes - though you can have as few as one, or
82+
as many 5,000 per cluster.
83+
84+
<br />
85+
<div style={{ textAlign: 'center' }}>
86+
<a target="\_blank" href={require('/assets/images/k8s-layer0.drawio.png').default}>
87+
<img src={Layer0} width="700" />
88+
</a>
89+
<br />
90+
</div>
91+
<br />
92+
93+
Once installed, Kubernetes creates
94+
[standardised interfaces](https://matt-rickard.com/kubernetes-interfaces) to control the hardware &
95+
software components of the underlying nodes (networking, storage, GPUs, CPU cores etc...) as well as
96+
a distributed key-value store which facilitates communication between all nodes in the cluster.
97+
98+
<br />
99+
<div style={{ textAlign: 'center' }}>
100+
<a target="\_blank" href={require('/assets/images/k8s-layers01.drawio.png').default}>
101+
<img src={Layers01} width="750" />
102+
</a>
103+
<br />
104+
</div>
105+
<br />
106+
107+
With the underlying hardware abstracted into a generic pool of resources, Kubernetes is then able to
108+
re-compose those assets into isolated environments called "Namespaces" where it deploys
109+
containerised workloads in groups called "Pods". This layer of Kubernetes is very similar to a
110+
typical container host but with many more features for multi-tenancy, security, and life-cycle
111+
management.
112+
113+
<br />
114+
<div style={{ textAlign: 'center' }}>
115+
<a target="\_blank" href={require('/assets/images/k8s-layers012.drawio.png').default}>
116+
<img src={Layers012} width="800" />
117+
</a>
118+
</div>
119+
<br />
120+
121+
Additional Reading:
122+
123+
- [Kubernetes Components](https://kubernetes.io/docs/concepts/overview/components/) - kubernetes.io
124+
- [A visual guide to Kubernetes networking fundamentals](https://opensource.com/article/22/6/kubernetes-networking-fundamentals) -
125+
Nived Velayudhan
126+
- [Thinking about the complexity of the Kubernetes ecosystem](https://erkanerol.github.io/post/complexity-of-kubernetes/) -
127+
Erkan Erol
128+
- [Ephemeral, Idempotent and Immutable Infrastructure ](https://cloudnativenow.com/topics/ephemeral-idempotent-and-immutable-infrastructure/) -
129+
Marc Hornbeek

‎docs/12-self-hosting/03-host-creation/02-bare-metal.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
import Metal from '/assets/images/Metal.drawio.png';
2+
3+
# Bare-Metal
4+
5+
The Host is the computer that will execute the runner application. This can be a desktop computer,
6+
laptop, Virtual Machine, or VPS from a cloud provider.
7+
8+
<div style={{ textAlign: 'center' }}>
9+
<a target="\_blank" href={require('/assets/images/Metal.drawio.png').default}>
10+
<img src={Metal} width="500" />
11+
</a>
12+
</div>
13+
<br />
14+
15+
## If your host is a local machine:
16+
17+
For a local machine you will need to perform a clean installation of the operating system. This
18+
means creating a bootable USB drive from an ISO file, booting the machine from the USB drive, and
19+
installing the OS. Links to download an official Live ISO file and installation guides are provided
20+
below. If you would like to create a custom ISO, try [PXEless](https://github.com/cloudymax/pxeless)
21+
or [Cubic](https://github.com/PJ-Singh-001/Cubic).
22+
23+
### Ubuntu
24+
25+
- Download the Ubuntu 22.04 LTS
26+
[server installer](https://ftp.snt.utwente.nl/pub/os/linux/ubuntu-releases/22.04.3/ubuntu-22.04.3-live-server-amd64.iso)
27+
- [Guide: Install Ubuntu 22.04 LTS on a local machine](https://ostechnix.com/install-ubuntu-server/)
28+
29+
### Debian
30+
31+
- Download the Debian 12
32+
[installation image](https://cdimage.debian.org/debian-cd/current/amd64/iso-dvd/debian-12.1.0-amd64-DVD-1.iso)
33+
- [Guide: Install Debian on a local system](https://www.linuxtechi.com/how-to-install-debian-11-bullseye/)
34+
35+
## If your host is a virtual-machine:
36+
37+
If you are using a VPS or VM, the OS should already be installed and admin user should already
38+
exist. Follow the appropriate guide in the provisioning section for your operating-system.
39+
40+
- [Ubuntu 22.04](../04-host-provisioning/02-ubuntu-setup.mdx)
41+
- [Debian 12](../04-host-provisioning/01-debian-setup.mdx)

0 commit comments

Comments
 (0)