Merge pull request #125 from netbootxyz/doc_refactor

Doc refactor, updated docker docs

.github/workflows/deploy.yml

@@ -23,12 +23,11 @@ jobs:
           wget https://raw.githubusercontent.com/netbootxyz/netboot.xyz/master/CHANGELOG.md -O external/changelog.md
           wget https://raw.githubusercontent.com/netbootxyz/build-pipelines/master/README.md -O external/build-automation.md
           wget https://raw.githubusercontent.com/netbootxyz/netboot.xyz/master/CONTRIBUTING.md -O external/contributing.md
-          curl https://raw.githubusercontent.com/netbootxyz/docker-netbootxyz/master/README.md | tail -n+7 > external/docker.md
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 22
 
       - name: Install dependencies
         run: yarn install

docs/booting/_category_.yml

@@ -0,0 +1,6 @@
+label: Booting Methods
+position: 3
+link:
+  type: generated-index
+  title: Booting Methods
+  description: Select your desired netboot.xyz boot method below...

docs/booting/grub.md

@@ -1,7 +1,8 @@
 ---
 id: grub
 title: Booting from an existing Linux installation using GRUB
-sidebar_label: Booting from GRUB
+sidebar_label: GRUB
+sidebar_position: 5
 description: "How to use GRUB to boot into netboot.xyz"
 hide_table_of_contents: true
 ---

docs/booting/ipxe.md

@@ -1,7 +1,8 @@
 ---
 id: ipxe
-title: Boot using iPXE
-sidebar_label: Boot using iPXE
+title: iPXE
+sidebar_label: iPXE
+sidebar_position: 4
 description: "Details how to chainload into netboot.xyz from iPXE"
 hide_table_of_contents: true
 ---

docs/booting/iso.md

@@ -1,7 +1,8 @@
 ---
 id: iso
-title: Booting with an ISO
-sidebar_label: Booting with an ISO
+title: ISO
+sidebar_label: ISO
+sidebar_position: 2
 description: "How to use an ISO to boot into netboot.xyz"
 hide_table_of_contents: true
 ---

docs/booting/qemu.md

@@ -1,7 +1,8 @@
 ---
 id: qemu
-title: Booting from QEMU
-sidebar_label: Booting from QEMU
+title: QEMU
+sidebar_label: QEMU
+sidebar_position: 6
 description: "Methods of booting into netboot.xyz using QEMU"
 hide_table_of_contents: true
 ---

docs/booting/tftp.md

@@ -1,7 +1,8 @@
 ---
 id: tftp
-title: Booting from TFTP
-sidebar_label: Booting from TFTP
+title: TFTP
+sidebar_label: TFTP
+sidebar_position: 3
 description: "Methods of booting into netboot.xyz using TFTP and DHCP"
 hide_table_of_contents: true
 ---

docs/booting/usb.md

@@ -1,7 +1,8 @@
 ---
 id: usb
-title: Booting from USB
-sidebar_label: Booting from USB
+title: USB
+sidebar_label: USB
+sidebar_position: 1
 description: "How to create a USB stick capable of booting into netboot.xyz"
 hide_table_of_contents: true
 ---

docs/booting/vmware.md

@@ -1,7 +1,8 @@
 ---
 id: vmware
-title: Boot using VMware
-sidebar_label: Boot using VMware
+title: VMware
+sidebar_label: VMware
+sidebar_position: 7
 description: "Using netboot.xyz in VMware to install a VM"
 hide_table_of_contents: true
 ---

docs/community/_category_.yml

@@ -0,0 +1,6 @@
+label: Community
+position: 5
+collapsed: true
+link:
+  type: generated-index
+  title: Community

docs/community/nbxyz-users.md

@@ -35,6 +35,7 @@ hide_table_of_contents: true
 
 ## Open Source Projects
 
+- [JetKVM - Hardware KVM with suppport for netboot.xyz](https://jetkvm.com/)
 - [Quickemu](https://github.com/quickemu-project/quickemu)
 - [Tinkerbell](https://tinkerbell.org/examples/netboot-xyz/)
 - [u-root](https://github.com/u-root/u-root/blob/main/cmds/exp/netbootxyz/netbootxyz.go)

docs/docker/_category_.yml

@@ -0,0 +1,6 @@
+label: Docker Container
+position: 4
+collapsed: false
+link:
+  type: generated-index
+  title: Docker Container

docs/docker/dhcp.md

@@ -0,0 +1,100 @@
+---
+title: DHCP Configurations
+sidebar_position: 4
+description: "Setting up DHCP for the netboot.xyz Docker Container"
+hide_table_of_contents: true
+---
+
+The netboot.xyz Docker image requires the usage of a DHCP server in order to function properly. If you have an existing DHCP server, usually you will need to make some small adjustments to make your DHCP server forward requests to the netboot.xyz container. The main settings in your DHCP or router that you will typically need to set are:
+
+* `tftp-server` also known as `next-server`, this option tells the client where to look for the boot file
+* `boot-file-name`, this option tells the client which boot file to load
+
+## Examples
+
+The following are some configuration examples for setting up a DHCP server to get started. The main configuration you will need to change are `SERVER_IP_ADDRESS` so that DHCP can direct the client to the server running the netboot.xyz Docker container. Because the Docker image is hosting a dnsmasq TFTP server, the boot files are pulled from it and then it will attempt to load the iPXE configs directly from the host. You can then modify and adjust them to your needs. See [booting from TFTP](https://netboot.xyz/docs/booting/tftp/) for more information.
+
+### Setting up dnsmasq
+
+To install dnsmasq as your DHCP server under Debian and Ubuntu run:
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="deb" label="Debian and Ubuntu" default>
+    ```shell
+    sudo apt install dnsmasq
+    ```
+  </TabItem>
+  <TabItem value="rhel" label="Redhat Based">
+    ```shell
+    sudo dnf install dnsmasq
+    ```
+  </TabItem>
+</Tabs>
+
+Set up your configuration file `/etc/dnsmasq.conf` with the following settings:
+
+:::note
+The following steps are examples and may not be the exact steps you need to take for your environment. Make sure to adjust the configuration to your needs.
+:::
+
+```shell
+# /etc/dnsmasq.conf
+
+# Set the DHCP Range and lease time
+dhcp-range=192.168.1.100,192.168.1.200,255.255.255.0,12h
+
+# Set the default gateway
+dhcp-option=option:router,192.168.1.1
+
+# Set tne DNS servers
+dhcp-option=option:dns-server,8.8.8.8,8.8.4.4
+
+# Standard PC BIOS
+dhcp-match=set:bios,60,PXEClient:Arch:00000
+dhcp-boot=tag:bios,netboot.xyz.kpxe,,SERVER_IP_ADDRESS
+
+# 64-bit x86 EFI
+dhcp-match=set:efi64,60,PXEClient:Arch:00007
+dhcp-boot=tag:efi64,netboot.xyz.efi,,SERVER_IP_ADDRESS
+
+# 64-bit x86 EFI (obsolete)
+dhcp-match=set:efi64-2,60,PXEClient:Arch:00009
+dhcp-boot=tag:efi64-2,netboot.xyz.efi,,SERVER_IP_ADDRESS
+
+# 64-bit UEFI for arm64
+dhcp-match=set:efi64-3,60,PXEClient:Arch:0000B
+dhcp-boot=tag:efi64-3,netboot.xyz-arm64.efi,,SERVER_IP_ADDRESS
+```
+
+A breakdown of the configuration:
+
+- `dhcp-range` sets the range of IP addresses and lease times that will be assigned to clients.
+- `dhcp-option` sets the default gateway and DNS servers.
+- `dhcp-boot` sets the boot file for different architectures, the `SERVER_IP_ADDRESS` should be replaced with the IP address of the host running the Docker container.
+- `dhcp-match` sets the match criteria for different architectures.
+
+Once the dnsmasq configuration is set, you can enable and start the service:
+
+```shell
+sudo systemctl enable dnsmasq
+sudo systemctl start dnsmasq
+```
+
+## netboot.xyz boot file types
+
+The following bootfile names can be set as the boot file in the DHCP configuration depending on your needs. They are baked into the Docker image:
+
+| bootfile name                   | description                                                          |
+| --------------------------------|----------------------------------------------------------------------|
+| `netboot.xyz.kpxe`              | Legacy DHCP boot image file, uses built-in iPXE NIC drivers          |
+| `netboot.xyz-undionly.kpxe`     | Legacy DHCP boot image file, use if you have NIC issues              |
+| `netboot.xyz.efi`               | UEFI boot image file, uses built-in UEFI NIC drivers                 |
+| `netboot.xyz-snp.efi`           | UEFI w/ Simple Network Protocol, attempts to boot all net devices    |
+| `netboot.xyz-snponly.efi`       | UEFI w/ Simple Network Protocol, only boots from device chained from |
+| `netboot.xyz-arm64.efi`         | DHCP EFI boot image file, uses built-in iPXE NIC drivers             |
+| `netboot.xyz-arm64-snp.efi`     | UEFI w/ Simple Network Protocol, attempts to boot all net devices    |
+| `netboot.xyz-arm64-snponly.efi` | UEFI w/ Simple Network Protocol, only boots from device chained from |
+| `netboot.xyz-rpi4-snp.efi`      | UEFI for Raspberry Pi 4, attempts to boot all net devices            |

docs/docker/overview.md

@@ -0,0 +1,39 @@
+---
+title: Overview
+sidebar_position: 1
+description: "Overview of the netboot.xyz docker container"
+hide_table_of_contents: true
+---
+
+The [netboot.xyz Docker image](https://github.com/netbootxyz/docker-netbootxyz) allows you to easily set up a local instance of netboot.xyz. The container is a small helper application written in node.js. It provides a simple web interface for editing menus on the fly, retrieving the latest menu release of netboot.xyz, and enables mirroring the downloadable assets from Github to your location machine for faster booting of assets.
+
+![netboot.xyz webapp](../../static/img/netboot.xyz-webapp.png)
+It is a great tool for developing and testing custom changes to the menus. If you have a machine without an optical drive that cannot boot from USB then having a local netboot server provides a way to install an OS. If you are looking to get started with netboot.xyz and don't want to manage iPXE menus, you should use the boot media instead of setting up a container.
+
+The container is built upon Alpine Linux and contains several components:
+
+* netboot.xyz [webapp](https://github.com/netbootxyz/webapp)
+* nginx for hosting local assets from the container
+* dnsmasq for providing TFTP services
+* syslog for providing tftp activity logs
+
+Services are managed in the container by [supervisord](http://supervisord.org/).
+
+The container runs under both x86_64 and ARM based architectures.
+
+## How it Works
+
+The following diagram details the flow of how netboot.xyz serves content to a client and how it works when the Docker container is used:
+
+```mermaid
+graph TD
+    A[Client Computer] -->|PXE Boot Request| B{netboot.xyz container?}
+    B -- Yes --> C[netboot.xyz container]
+    C -- Local request --> D[Serve netboot.xyz]
+    C -- Unavailable --> E[boot.netboot.xyz]
+    B -- No --> E
+    E -->|Internet Request| F[boot.netboot.xyz]
+    F --> G[Serve netboot.xyz]
+    G --> H[Client Boots OS]
+    D --> H
+```

docs/docker/parameters.md

@@ -0,0 +1,20 @@
+---
+title: Container Parameters
+sidebar_position: 3
+description: "Setting up the netboot.xyz Docker Container"
+hide_table_of_contents: true
+---
+
+Container images are configured using parameters passed at runtime. These parameters are separated by a colon and indicate `<external>:<internal>` respectively. For example, `-p 8080:80` would expose port `80` from inside the container to be accessible from the host's IP on port `8080` outside the container.
+
+| Parameter | Function |
+| :-------: |  ------- |
+| `-p 3000` | Web configuration interface. |
+| `-p 69/udp` | TFTP Port. |
+| `-p 80` | NGINX server for hosting assets. |
+| `-e WEB_APP_PORT=3000` | Specify a different port for the web configuration interface to listen on. |
+| `-e NGINX_PORT=80` | Specify a different port for NGINX service to listen on. |
+| `-e MENU_VERSION=2.0.84` | Specify a specific version of boot files you want to use from netboot.xyz (unset pulls latest) |
+| `-e TFTPD_OPTS='--tftp-single-port'` | Specify arguments for the TFTP server (this example makes TFTP send all data over port 69) |
+| `-v /config` | Storage for boot menu files and web application config |
+| `-v /assets` | Storage for netboot.xyz bootable assets (live CDs and other files) |