How to Run netboot.xyz via LinuxServer.io’s Docker Image

I started setting up a new server recently and had an idea — using TFTP to boot a computer from the network instead of local media. I’ve known about this for a long time, but I never had a concrete use for it until recently. And in all honesty, I don’t strictly need it, but I figured, why not try it now?

This is my fourteenth post documenting images I use at home. You can also read about how I run the Unifi controller, how I run Plex, how I update DuckDNS, how I run Duplicacy, how I run Heimdall, how I run Librespeed, how I run Home Assistant, how I run NetBox, how I run Scrutiny, how I run OpenVSCode Server, how I run QDirStat, how I run WireGuard, and how I run Z-Wave JS UI.

About LinuxServer.io

LinuxServer.io describes their organization as:

A group of like-minded enthusiasts from across the world who build and maintain the largest collection of Docker images on the web. At our core are the principles behind Free and Open Source Software. Our primary goal is to provide easy-to-use and streamlined Docker images with clear and concise documentation.

I’ve been using LinuxServer.io images for a couple of years. That’s because they’re easy to use, and they’re clearly and concisely documented. I tend to check here first when I need a new image.

Running the Image via docker-compose

LinuxServer.io only officially supports running the image via docker run or, preferably, docker-compose. Here is what the relevant section of my docker-compose.yml file looks like:

networks:
  netbootxyz:
    name: netbootxyz

  netbootxyz:
    container_name: netbootxyz
    image: lscr.io/linuxserver/netbootxyz:0.6.7-ls87
    restart: unless-stopped
  
    env_file:
      - ./common.env
      - ./secret.env
    environment:
      - PORT_RANGE=30000:30010
    networks:
      - netbootxyz
    ports:
      - 69:69/udp
      - 3003:3000
      - 8082:80
    volumes:
      - ${SERVICE_DATA_DIR}/netbootxyz:/config
      - ${MEDIA_DIR}/Operating Systems:/assets

About This Configuration

First, we define the network and image to use for this container. I always prefer to pin to specific versions when possible.

In the environment stanza, we specify the one environment variable: PORT_RANGE. This variable is not strictly required, but I like explicitly listing ports in my docker-compose.yml file; when I run into port conflicts, this makes it a bit easier for me to identify the offenders. 30000:30010 is the default port range.

Next, I specify the container’s port mappings; in this case, UDP port 69, TCP ports 3000 and 80. Note that I needed to map to ports 3003 and 8082 instead of 3000 and 8080 due to the port conflicts mentioned above. This is why I like having ports explicitly defined in this file – for easy searchability.

Lastly, I have my volume mappings. The first is the typical /config directory required by LinuxServer.io images, which I have mapped to the directory with all of my service data. /assets is where netboot.xyz will look for images, and I have that mapped to my NAS’s media directory, which includes operating systems. Miraculously, YAML syntax is perfectly happy with the unescaped space in my volume path. I’m sure that will never happen again.

I can now boot up the container via docker-compose, open a browser, and connect to netboot.xyz at my server’s port 3003.

Configuring the Network for Network Boot

Whatever is responsible for DHCP on your network — likely your router — needs to be configured to know where to point network boot clients. LinuxServer.io has a nice writeup about updating several router configurations. In my case — “Unifi Security Gateway (with the controller)” — I needed to enable network boot, specify the server’s IP, and boot image.

Running netboot.xyz via LinuxServer.io’s Image

Finally the payout — after all the above, I set up a new server by network booting and installing Proxmox Virtual Environment. I now have one more server and one fewer installation media lying around.

Thanks to the netboot.xyz team for creating this great software and the LinuxServer.io team for the great image.