Fedora CoreOS Homeserver¶

This project explores a pragmatic way to use Fedora CoreOS (FCOS) as a "set-and-forget" home server by lowering the barrier to its initial provisioning, while staying aligned with FCOS design principles.

It consists of:

• A set of Jinja2 templates describing self-contained services (storage, reverse proxy, applications).
• A single metaconfig.yaml that declaratively selects and parametrizes those templates.
• A build_config.py script that renders and merges the templates into a valid Butane configuration, which is then consumed by the standard FCOS installation workflow.

core:
  ssh_authorized_keys:
    - <MY PUBLIC SSH KEY>

caddy:
  image: docker.io/library/caddy:2.10
  http_port: 80
  https_port: 443
  public_sites:
    - hostname: jellyfin.mydomain.com
      port: 3002

jellyfin:
  image: docker.io/jellyfin/jellyfin:10
  http_port: 3002
  media_volumes:
    - /var/hdd/Movies:/media/Movies:ro,Z
  hostname: jellyfin.mydomain.com

Each top-level key selects one template; the values under it are the only decisions the template leaves to you.

Why Fedora CoreOS?¶

Fedora CoreOS is primarily known as a building block for enterprise container platforms. That background is precisely what makes it attractive for a long-lived home server:

• Immutable OS
  • The base system is read-only and versioned.
  • Configuration drift and vulnerabilities are minimized.
• Reproducibility
  • All configuration is done at first boot using a configuration file.
  • Manual configuration through SSH should be exceptional.
• Optimized for containers
  • The OS provides a minimal, container-focused userland.
  • Podman is the default container runtime, rootless mode is well supported.
  • systemd Quadlet is a first-class mechanism for managing containers as services.
• Automatic, transactional updates
  • OS updates are applied atomically and rolled back automatically on failure.
  • No manual maintenance is expected.

The main barrier to entry therefore remains the initial configuration, which is the purpose of this project.

Where to start¶

• Installation — edit metaconfig.yaml, build the Butane configuration and install Fedora CoreOS with it.
• Maintenance — SSH access, the per-service users, reading logs and tweaking a running service.
• Debugging services — the commands for a service that does not come up: journal, Quadlet generator, health checks, volumes.
• Templates — every available service and the parameters it takes.
• Design rationale — how the generated configuration maps to Fedora CoreOS, Ignition, systemd and Podman. Recommended reading before adapting the project to your own setup.
• Adding a template — writing a new service template, trying it on a running server with the ad hoc script, and documenting it.

What is in the box¶

License¶

Licensed under the MIT License.