Prerequisites for the tutorials
The following tutorials are focused on helping you get started with Fedora CoreOS by learning how to automatically configure (or provision) an instance on first boot. Each tutorial has its roots in the previous one thus it is recommended to follow them sequentially.
If you don’t know what Fedora CoreOS is, you can refer to the FAQ for more information.
If you need any help or need to ask any questions while going through those tutorials, please join the Matrix room, or join our discussion board. If you find any issue in the tutorial, please report them in the fedora-coreos-docs issue tracker. |
You should start with the setup instructions from this page as they must be completed first to be able to follow the tutorials.
-
Enabling autologin and custom hostname
-
In this tutorial, you will write your first Ignition config and start a Fedora CoreOS instance with it.
-
-
Starting a service on first boot
-
In this tutorial, you will learn how to start a custom script via a systemd unit on the first boot of a Fedora CoreOS instance.
-
-
SSH access and starting containers
-
In this tutorial, you will learn how to start a container at first boot with podman.
-
-
Launching a user-level systemd unit on boot
-
There are times when it’s helpful to launch a user-level systemd unit without having to log in. This tutorial demonstrates creating a user-level systemd unit that launches on boot.
-
-
-
In this tutorial, you will learn how automatic updates are handled in Fedora CoreOS and how to rollback in case of failures.
-
Virtualization with libvirt
These tutorials are written targeting a Linux environment with a working libvirt
setup and hardware virtualization support via KVM
. There is, however, nothing specific to the libvirt
environment in those tutorials and you can thus try the same configurations on any platform where you have console access (or you can skip to the SSH access tutorial to get remote access).
For instructions to set up libvirt
and KVM
you may refer to the Getting started with virtualization guide from Fedora. Although this setup guide is focused on Fedora, the tutorials should work on any distribution with libvirt
installed and running.
Local working directory
To keep all configuration files and Fedora CoreOS images in the same place, we will create a new directory to work from:
mkdir ~/coreos
cd ~/coreos
SSH public key
Some of the tutorials add an SSH public key to the instances to allow for SSH access as opposed to serial console access. Please place a public key in your current working directory under the filename
ssh-key.pub
. For example, for a RSA keypair the default location would be in ~/.ssh/id_rsa.pub
:
cp ~/.ssh/id_rsa.pub ssh-key.pub
CoreOS tools
For the tutorials, we will need the following tools:
-
Butane: To generate Ignition configuration from Butane config files.
-
coreos-installer
: To download the latest Fedora CoreOS QCOW2 image. -
ignition-validate
: To validate Ignition configuration files.
Setup with podman
or docker
All the tools required to work with Fedora CoreOS are available from containers hosted on quay.io:
podman pull quay.io/coreos/butane:release
podman pull quay.io/coreos/coreos-installer:release
podman pull quay.io/coreos/ignition-validate:release
To make it simpler to type, you may add the following aliases to your shell configuration:
alias butane='podman run --rm --interactive \
--security-opt label=disable \
--volume ${PWD}:/pwd --workdir /pwd \
quay.io/coreos/butane:release'
alias coreos-installer='podman run --pull=always \
--rm --interactive \
--security-opt label=disable \
--volume ${PWD}:/pwd --workdir /pwd \
quay.io/coreos/coreos-installer:release'
alias ignition-validate='podman run --rm --interactive \
--security-opt label=disable \
--volume ${PWD}:/pwd --workdir /pwd \
quay.io/coreos/ignition-validate:release'
You can then use coreos-installer
to download the latest stable image with:
coreos-installer download -p qemu -f qcow2.xz --decompress
To make the tutorial simpler, you should rename the image that we have just downloaded to a shorter name:
mv fedora-coreos-40.20240808.3.0-qemu.x86_64.qcow2 fedora-coreos.qcow2
You are now ready to proceed with the first tutorial.
Installing via Fedora packages
All three tools (Butane, coreos-installer
, and ignition-validate
) are available as Fedora packages:
# Installing the tools
sudo dnf install -y butane coreos-installer ignition-validate
# Downloading the latest Fedora CoreOS stable QCOW2 image
coreos-installer download -p qemu -f qcow2.xz --decompress
To make the tutorial simpler, you should rename the image that we have just downloaded to a shorter name:
mv fedora-coreos-40.20240808.3.0-qemu.x86_64.qcow2 fedora-coreos.qcow2
You are now ready to proceed with the first tutorial.
Manual download
If none of the previous solutions work for you, you can still manually download Fedora CoreOS from fedoraproject.org with:
RELEASE="40.20240808.3.0"
curl -O https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/$RELEASE/x86_64/fedora-coreos-$RELEASE-qemu.x86_64.qcow2.xz
curl -O https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/$RELEASE/x86_64/fedora-coreos-$RELEASE-qemu.x86_64.qcow2.xz.sig
Once the archive has been downloaded, make sure to verify its integrity by following the instructions available by clicking on the Verify signature & SHA256
button. You will have to download the checksum file, the signature and Fedora GPG keys to verify your download:
curl https://fedoraproject.org/fedora.gpg | gpg --import
gpg --verify fedora-coreos-$RELEASE-qemu.x86_64.qcow2.xz.sig
Once you have verified the archive, you can extract it with:
unxz fedora-coreos-$RELEASE-qemu.x86_64.qcow2.xz
To make the tutorial simpler, you should rename the image that we have just downloaded to a shorter name:
mv fedora-coreos-40.20240808.3.0-qemu.x86_64.qcow2 fedora-coreos.qcow2
You should then download the latest Butane and ignition-validate releases from GitHub:
# Butane
curl -OL https://github.com/coreos/butane/releases/download/v0.21.0/butane-x86_64-unknown-linux-gnu
curl -OL https://github.com/coreos/butane/releases/download/v0.21.0/butane-x86_64-unknown-linux-gnu.asc
gpg --verify butane-x86_64-unknown-linux-gnu.asc
mv butane-x86_64-unknown-linux-gnu butane
chmod a+x butane
# ignition-validate
curl -OL https://github.com/coreos/ignition/releases/download/v2.19.0/ignition-validate-x86_64-linux
curl -OL https://github.com/coreos/ignition/releases/download/v2.19.0/ignition-validate-x86_64-linux.asc
gpg --verify ignition-validate-x86_64-linux.asc
mv ignition-validate-x86_64-linux ignition-validate
chmod a+x ignition-validate
You may then set up aliases for butane
and ignition-validate
:
alias butane="${PWD}/butane"
alias ignition-validate="${PWD}/ignition-validate"
Or move those commands to a folder in your $PATH
, for example:
mv butane ignition-validate "${HOME}/.local/bin/"
# Or
mv butane ignition-validate "${HOME}/bin"
You are now ready to proceed with the first tutorial.
Want to help? Learn how to contribute to Fedora Docs ›