Skip to content

fix(install): Docker on AlmaLinux, Rocky and Oracle Linux, and the kernel modules RHEL 10 images leave out - #242

Merged
alexevladgabriel merged 1 commit into
feat/fumadocs-nextfrom
fix/install-sh-rhel-family
Nov 16, 2026
Merged

alexevladgabriel merged 1 commit into
feat/fumadocs-nextfrom
fix/install-sh-rhel-family

Conversation

@alexevladgabriel

@alexevladgabriel alexevladgabriel commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Why

curl -fsSL https://pelican.dev/install.sh | sudo bash failed on the RHEL family:

  1. AlmaLinux and Rocky Linux 8, 9 and 10: Docker never installs. get.docker.com adds Docker's repo named after them (linux/rocky/…, linux/alma/…). Those repos exist but contain no docker-ce packages, and neither does linux/oracle/…. The script stops within seconds with "Unable to find a match: docker-ce".
  2. CentOS Stream 10: Docker installs but won't start. The image lacks the kernel module xt_addrtype, which ships in kernel-modules-extra.
  3. Running the script again didn't help. It saw Docker installed and failed at the same systemctl enable --now docker.

Testing turned up two more:

  1. Swarm can't reach its services when xt_ipvs is missing. The CentOS Stream, AlmaLinux and Rocky Linux 10 images and Oracle Linux's UEK kernel all lack it. Docker runs and the script finishes, but Traefik answers 502.
  2. A fresh CentOS Stream 10 failed even after the module was added. get.docker.com starts Docker during the install, before the module is there. The failed starts left systemd refusing new ones ("Start request repeated too quickly").

What changes

All in public/install.sh.

  • AlmaLinux, Rocky Linux, Oracle Linux and other RHEL rebuilds install Docker from Docker's CentOS repo with dnf. Detection uses /etc/os-release: ID not in centos/rhel/fedora, with ID_LIKE containing rhel or centos, plus Oracle's ol, whose ID_LIKE is only fedora. The repo file has the same name as the one get.docker.com writes, so it also replaces what a failed earlier run added. Ubuntu, Debian, Fedora, CentOS Stream and RHEL still use get.docker.com.
  • Kernel modules: before Docker is installed, and on every run, it checks xt_addrtype and xt_ipvs.
    • If either is missing, it installs kernel-modules-extra, or on UEK kernel-uek-modules-extra and kernel-uek-modules-extra-netfilter, for the running kernel.
    • It falls back to the newest version, and tells you to reboot if the modules are still missing.
    • A Docker that was already running is restarted, so it sets up its rules again.
    • On non-dnf systems it only warns.
  • Recovery: systemctl reset-failed docker before starting it. If Docker still doesn't start, the script prints its last 20 log lines and says so.
  • The docs' "Installing Docker" section explains the CentOS repo and the module packages for people installing by hand.

Verification

Real VMs with Lima (arm64, Apple Virtualization). Each one: a fresh image, the script run with --skip-dns-check, then GET /installer on the server.

System (fresh image) Before (current script) After
Rocky Linux 9.8 "Unable to find a match: docker-ce" Docker 29.9.3 from the CentOS repo, /installer 200
CentOS Stream 10 Docker won't start (addrtype missing); a second run fails the same way modules added before Docker, /installer 200 in one run
AlmaLinux 10.2 not run (same as Rocky) CentOS repo + xt_addrtype/xt_ipvs, /installer 200
Rocky Linux 10.2 not run CentOS repo + modules, /installer 200
Oracle Linux 9.8 (UEK 6.12) not run CentOS repo + UEK modules, /installer 200
  • Recovering a broken server: the fixed script was rerun on servers the old script (or an earlier version of this fix) left broken:

    • Rocky 9, where Docker never installed;
    • CentOS Stream 10, where Docker didn't start;
    • Oracle 9, where the Panel answered 502.

    All three ended with /installer 200. A third run on a working server changes nothing.

  • Rocky Linux 8 and AlmaLinux 8: the EL8 arm64 images don't boot under Apple Virtualization, so only the install step was checked, in rockylinux:8 and almalinux:8 containers. Docker's CentOS repo installs docker-ce 26.1.3, the last version Docker built for EL8.

  • bun test: 149 pass. scripts/install-sh.test.mjs gains 11 cases on which install method each system gets, using a fake os-release (PELICAN_OS_RELEASE, for the tests only); the 4 RHEL-rebuild cases fail on the old script.

  • shellcheck is clean. bun run typecheck and bun run build (with check:content and check:paths) pass.

Not checked:

  • x86_64 droplets: the VMs were arm64. The packages and module names are the same on both, but this wasn't run there.
  • A full run on Rocky 8 and AlmaLinux 8 (only the package install, in a container).
  • Oracle Linux 8 and 10.
  • The reboot path, where the module package exists only for a newer kernel.

Note

Fix Docker install on AlmaLinux, Rocky, and Oracle Linux and add missing kernel modules

  • The installer now detects RHEL/CentOS-family distributions via os-release (ID, ID_LIKE) and installs Docker from Docker's CentOS repository with dnf on matching systems like AlmaLinux, Rocky, and Oracle Linux, instead of the generic Docker script.
  • Before installing Docker, the installer probes for xt_addrtype and xt_ipvs with modprobe and installs matching kernel-modules-extra (or UEK variants for Oracle kernels) when they are missing. It aborts with guidance if the modules stay unavailable, and restarts Docker afterward when packages were added.
  • Docker service start failures now print recent journal lines and exit with an error. The existing-Docker status message reports a missing server version as "not running yet."
  • Updates the docs with matching install steps for these distributions, and adds dry-run tests in install-sh.test.mjs covering the distribution selection and the module/start ordering.
  • Risk: the rhel_rebuild predicate excludes CentOS, RHEL, Fedora, and unset IDs; check that new distributions match expectations, and note the os-release path can be overridden via PELICAN_OS_RELEASE.

Macroscope summarized 363371e.

…rnel modules RHEL 10 images leave out

- AlmaLinux, Rocky Linux and Oracle Linux 8, 9 and 10: get.docker.com adds Docker's repo named
  after them, which has no Docker Engine packages ("Unable to find a match: docker-ce"). They now
  install from Docker's CentOS repo.
- CentOS Stream, AlmaLinux and Rocky Linux 10 images lack xt_addrtype and xt_ipvs (Docker won't
  start / Swarm can't reach its services, 502), Oracle Linux's UEK kernel lacks xt_ipvs. The script
  installs kernel-modules-extra (or kernel-uek-modules-extra and -netfilter) for the running kernel
  before Docker, and restarts a Docker that was already running.
- Running the script again after a failed start now recovers: the module check runs every time,
  systemd's "start request repeated too quickly" lock is cleared, and a failed start shows Docker's
  last log lines.
- The docs' "Installing Docker" section says how to do the same by hand.
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 7a95bb18-1d7f-480f-8972-0d263c55c4ca

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@alexevladgabriel
alexevladgabriel marked this pull request as ready for review November 16, 2026 02:39
@alexevladgabriel
alexevladgabriel merged commit d0e3107 into feat/fumadocs-next Nov 16, 2026
2 checks passed
@alexevladgabriel
alexevladgabriel deleted the fix/install-sh-rhel-family branch November 16, 2026 02:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant