From 38c253740008fe5955fd6e45cfb48d6296fcbbbc Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sat, 13 Dec 2025 14:09:21 -0500 Subject: [PATCH] docs: Add comprehensive repository documentation - Add detailed overview of what the repository provides - Document all included components (tarball, services, shell integration) - Add practical examples for using in custom bootc images - Include basic, advanced, and Universal Blue integration examples - Document build process and runtime behavior - Add environment variables and file locations reference - Include systemd service details - Add troubleshooting section for common issues - Document contribution guidelines and related projects --- README.md | 265 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 263 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e2099f3..7377803 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,267 @@ # brew -Repository for generating Homebrew tarballs for redistribution on image-based systems via an OCI image +Repository for generating Homebrew tarballs for redistribution on image-based systems via an OCI image. -This includes general settings you'd want to use when using homebrew on a `bootc` system, including a tarball and services for setting it up +This includes general settings you'd want to use when using Homebrew on a `bootc` system, including a tarball and services for setting it up. +## Overview + +This repository builds an OCI container image that packages: +- A pre-installed Homebrew tarball (`homebrew.tar.zst`) +- Systemd services for automated setup, updates, and upgrades +- Shell integration scripts (bash, fish) +- Security limits and tmpfiles configuration + +The image is designed to be consumed by custom bootc-based container images, providing a seamless way to include Homebrew package management in immutable Linux systems. + +## What's Included + +### Homebrew Tarball +- Pre-built Homebrew installation at `/usr/share/homebrew.tar.zst` +- Built from official Homebrew installer in a clean Wolfi container +- Compressed with zstd for efficient storage + +### Systemd Services + +#### brew-setup.service +Runs on first boot to extract and configure Homebrew: +- Extracts tarball to `/var/home/linuxbrew/.linuxbrew` +- Sets appropriate ownership (UID 1000) +- Creates marker file to prevent re-running + +#### brew-update.timer & brew-update.service +Automatically keeps Homebrew up to date: +- Runs daily to update Homebrew itself +- Ensures formula database is current + +#### brew-upgrade.timer & brew-upgrade.service +Automatically upgrades installed packages: +- Runs on a regular schedule +- Keeps installed packages up to date + +### Shell Integration +- **Bash**: `/etc/profile.d/brew.sh` - Automatically configures Homebrew environment +- **Fish**: `/usr/share/fish/vendor_conf.d/ublue-brew.fish` - Fish shell support +- **Bash Completion**: `/etc/profile.d/brew-bash-completion.sh` + +### Configuration Files +- **Security Limits**: `/etc/security/limits.d/30-brew-limits.conf` +- **Tmpfiles**: `/usr/lib/tmpfiles.d/homebrew.conf` +- **Systemd Presets**: `/usr/lib/systemd/system-preset/01-homebrew.preset` + +## Using in Custom bootc Images + +### Basic Example + +To include Homebrew in your custom bootc image, copy the files from this repository's OCI image: + +```dockerfile +FROM quay.io/fedora/fedora-bootc:41 + +# Copy Homebrew files from the brew image +COPY --from=ghcr.io/ublue-os/brew:latest /system_files / +``` + +This will: +1. Install the Homebrew tarball to `/usr/share/homebrew.tar.zst` +2. Install all systemd services and timers +3. Add shell integration scripts +4. Configure system limits and tmpfiles + +On first boot, `brew-setup.service` will automatically: +1. Extract Homebrew to `/var/home/linuxbrew/.linuxbrew` +2. Set up proper permissions +3. Make Homebrew ready to use + +### Advanced Example with Pre-installed Packages + +If you want to pre-install Homebrew packages in your image: + +```dockerfile +FROM quay.io/fedora/fedora-bootc:41 + +# Copy Homebrew files +COPY --from=ghcr.io/ublue-os/brew:latest /system_files / + +# Install Homebrew packages during image build +RUN mkdir -p /var/home/linuxbrew && \ + tar --zstd -xvf /usr/share/homebrew.tar.zst -C /tmp && \ + mv /tmp/home/linuxbrew/.linuxbrew /var/home/linuxbrew/ && \ + eval "$(/var/home/linuxbrew/.linuxbrew/bin/brew shellenv)" && \ + brew install gcc neovim ripgrep && \ + brew cleanup && \ + tar --zstd -cvf /usr/share/homebrew.tar.zst /var/home/linuxbrew/.linuxbrew && \ + rm -rf /var/home/linuxbrew/.linuxbrew /tmp/home +``` + +This approach: +1. Extracts the Homebrew tarball during build +2. Installs desired packages +3. Re-compresses everything back into the tarball +4. Removes temporary files + +On first boot, users get Homebrew with your pre-installed packages ready to use. + +### Using with Universal Blue Images + +For Universal Blue-based images, you can use this as a MODULE: + +```dockerfile +FROM ghcr.io/ublue-os/bluefin-dx:latest + +# Include Homebrew support +COPY --from=ghcr.io/ublue-os/brew:latest /system_files / +``` + +### Disabling Auto-Updates + +If you want Homebrew installed but prefer manual updates: + +```dockerfile +FROM quay.io/fedora/fedora-bootc:41 + +COPY --from=ghcr.io/ublue-os/brew:latest /system_files / + +# Disable automatic update timers +RUN systemctl disable brew-update.timer && \ + systemctl disable brew-upgrade.timer +``` + +## Building the Image + +### Prerequisites +- Podman or Docker +- Make (optional, for using Justfile) + +### Build Command + +```bash +podman build -t brew:latest -f ./Containerfile . +``` + +Or using just: + +```bash +just build +``` + +### Multi-Architecture Builds + +The GitHub Actions workflow builds for both amd64 and arm64 architectures automatically. + +## How It Works + +### Build Process + +1. **Builder Stage**: Uses Wolfi base image to create a minimal, secure build environment + - Installs necessary tools (curl, git, zstd, tar, etc.) + - Downloads official Homebrew installer + - Runs Homebrew installation in isolated environment + - Compresses installation to tarball with zstd + +2. **Final Stage**: Creates a scratch image with just the necessary files + - Copies system configuration files + - Includes compressed Homebrew tarball + - No runtime dependencies + +### Runtime Behavior + +When a bootc system using this image boots: + +1. **First Boot**: + - `brew-setup.service` detects no existing Homebrew installation + - Extracts tarball to `/var/home/linuxbrew/.linuxbrew` + - Sets ownership to first user (UID 1000) + - Creates marker file to prevent re-extraction + +2. **Subsequent Boots**: + - `brew-setup.service` skips (marker file exists) + - `brew-update.timer` runs daily to update Homebrew + - `brew-upgrade.timer` runs to upgrade packages + - Shell integration automatically available to users + +## Environment Variables + +When users log in, the shell integration scripts set up: + +```bash +HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew" +HOMEBREW_CELLAR="/home/linuxbrew/.linuxbrew/Cellar" +HOMEBREW_REPOSITORY="/home/linuxbrew/.linuxbrew/Homebrew" +PATH="/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin:$PATH" +MANPATH="/home/linuxbrew/.linuxbrew/share/man:$MANPATH" +INFOPATH="/home/linuxbrew/.linuxbrew/share/info:$INFOPATH" +``` + +## File Locations + +| Path | Purpose | +|------|---------| +| `/usr/share/hobrew.tar.zst` | Compressed Homebrew installation | +| `/var/home/linuxbrew/.linuxbrew` | Extracted Homebrew (runtime) | +| `/etc/.linuxbrew` | Marker file indicating setup cn| `/etc/profile.d/brew.sh` | Bash shell integration | +| `/usr/share/fish/vendor_conf.d/ublue-brew.fish` | Fish shell integration | + +## Systemd Service Details + +### brew-setup.service + +**Type**: oneshot +**When**: First boot only +**Conditions**: +- `/etc/.linuxbrew` does not exist +- `/var/home/linuxbrew/.linuxbrew` does not exist +- `/usr/share/homst` exists + +### brew-update.timer + +**Schedule**: Daily +**Purpose**: Update Homebrew repository and formula database + +### brew-upgrade.timer + +**Schedule**: Regular intervals +**Purpose**: Upgrade installed Homebrew packages + +## Troubleshooting + +### Homebrew not in PATH + +Make sure your shell is properly loading the profile scripts: +```bash +source /etc/profile.d/brew.sh +``` + +Or manually: +```bash +eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" +``` + +### Permission Issues + +Homebrew expects to be owned by the first user (UID 1000). If you have permission issues: +```bash +sudo chown -R $(id -u):$(id -g) /var/home/linuxbrew +``` + +### Force Re-extraction + +If you need to re-extract the Homebrew tarball: +```bash +sudo rm /etc/.linuxbrew +sudo systemctl start brew-setup.service +``` + +## License + +See [LICENSE](LICENSE) file for details. + +## Contributing + +This repository is part of the Universal Blue project. Contributions are welcome via pull requests. + +## Related Projects + +- [Universal Blue](https://universal-blue.org/) +- [Homebrew](https://brew.sh/) +- [bootc](https://containers.github.io/bootc/)