====== Network-booting Flatcar Linux ======

{{ :logos:flatcar.png?137x84|Flatcar logo}}

You can use iPXE to boot into [[https://www.flatcar.org/|Flatcar Container Linux]] in order to run container payloads.  You can control the behaviour of Flatcar Linux by providing an [[https://www.flatcar.org/docs/latest/provisioning/ignition/|Ignition]] configuration file generated by the [[https://www.flatcar.org/docs/latest/provisioning/config-transpiler/|Butane]] utility in order to configure networking, register SSH keys, define the running container services, etc.

===== Boot script =====

Create an iPXE [[:scripting|script]] file ''flatcar.ipxe'' containing:

  #!ipxe
  
  set mirror http://stable.release.flatcar-linux.net/amd64-usr/current
      
  kernel ${mirror}/flatcar_production_pxe.vmlinuz flatcar.first_boot=1
  initrd ${mirror}/flatcar_production_pxe_image.cpio.gz
  initrd config.ign /usr/share/oem/config.ign mkdir=1
  boot

If you have mirrored the Flatcar tree locally, then you should change the line

  set mirror http://stable.release.flatcar-linux.net/amd64-usr/current

to point to the URI of your local mirror.  Booting and installing from a local mirror will be several times faster than using the public ''stable.release.flatcar-linux.net'' mirror.

===== Flatcar configuration =====

Create a [[https://www.flatcar.org/docs/latest/provisioning/config-transpiler/|Butane]] configuration file ''config.yml'' containing:

  variant: flatcar
  version: 1.0.0
  
  systemd:
    units:
      - name: nginx-demo.service
        enabled: true
        contents: |
          [Unit]
          Description=Minimal NGINX demo
          After=network-online.target
          Wants=network-online.target
  
          [Service]
          ExecStart=/usr/bin/docker run --rm -p 80:80 nginxdemos/hello
          Restart=always
  
          [Install]
          WantedBy=multi-user.target

This example configuration file will just run a simple [[https://hub.docker.com/r/nginxdemos/hello/|Nginx demo container]].

Compile your ''config.yml'' file to the Ignition configuration file ''config.ign'':

  butane --strict --output config.ign config.yml

Place your ''config.ign'' configuration file in the same directory as your ''flatcar.ipxe'' script.

===== Booting =====

Boot using iPXE from the URI of your ''flatcar.ipxe'' script, e.g. ''%%http://my.web.server/flatcar.ipxe%%''.  You should see iPXE download and boot into Flatcar Linux, which will then download and start the specified container:

{{ :screenshots:flatcar_boot.png?360x200 |Booting from flatcar.ipxe script}}

{{ :screenshots:flatcar_run.png?360x200 |Flatcar Linux up and running}}

You can verify that the Nginx demo container is running inside Flatcar Linux by browsing to its IP address to see a basic status page:

{{ :screenshots:flatcar_nginx.png?570x662 |Flatcar Linux running Nginx demo container}}

You can now try modifying (and recompiling) the ''config.yml'' file to run whatever container workloads you want.  Congratulations on successfully network-booting into Flatcar Container Linux!

{{ :clipart:smile.png?200x200 |Success}}