diff --git a/README.md b/README.md index dd4cc49..fc932e4 100644 --- a/README.md +++ b/README.md @@ -2,29 +2,229 @@ [![build-ublue](https://github.com/sidusIO/sediment/actions/workflows/build.yml/badge.svg)](https://github.com/sidusIO/sediment/actions/workflows/build.yml) -Sediment is an immutable desktop OS built with [rpm-ostree](https://coreos.github.io/rpm-ostree/) and based on [Fedora Atomic Desktops - Sway](https://fedoraproject.org/atomic-desktops/sway/). - -## Getting Started - -To get started you can either: - -### Create a new system using the ISO -No further explanation needed I hope. - -### Rebase onto this image from another installation -- First rebase to the unsigned image, to get the proper signing keys and policies installed: - ``` - rpm-ostree rebase ostree-unverified-registry:ghcr.io/sidusIO/sediment:latest - ``` -- Reboot to complete the rebase: - ``` - systemctl reboot - ``` -- Then rebase to the signed image, like so: - ``` - rpm-ostree rebase ostree-image-signed:docker://ghcr.io/sidusIO/sediment:latest - ``` -- Reboot again to complete the installation - ``` - systemctl reboot - ``` +Sediment is an immutable desktop operating system built with [rpm-ostree](https://coreos.github.io/rpm-ostree/) and based on [Fedora Atomic Desktops - Sway](https://fedoraproject.org/atomic-desktops/sway/). It provides a modern, tiling window manager experience with carefully curated tools and configurations for development and daily use. + +## ✨ Features + +- **Immutable OS**: Built on rpm-ostree for reliable, atomic updates +- **Sway Window Manager**: Efficient tiling Wayland compositor +- **GDM Display Manager**: GNOME Display Manager replacing SDDM for better integration +- **Fish Shell**: Modern shell set as default (`/usr/bin/fish`) +- **Docker Support**: Pre-installed and configured Docker CE +- **Distrobox**: Easy container-based development environments +- **Automatic Updates**: System updates every 6 hours via systemd timer +- **Fingerprint Authentication**: Built-in fingerprint reader support +- **Screen Capture Tools**: grim, slurp, swappy, and wf-recorder for screenshots and recordings +- **Development Tools**: Kubernetes client and essential utilities +- **Premium Fonts**: Pre-installed Google Fonts (Roboto, Open Sans) and Nerd Fonts (FiraCode, Hack, SourceCodePro, Terminus, JetBrainsMono) + +## 📦 Installation + +### Option 1: Install from ISO + +1. Download the latest ISO from the [auto-iso release](https://github.com/sidusIO/sediment/releases/tag/auto-iso) +2. Create a bootable USB drive using tools like [Fedora Media Writer](https://flathub.org/apps/org.fedoraproject.MediaWriter) or `dd` +3. Boot from the USB and follow the installation wizard + +### Option 2: Rebase from Existing Fedora Atomic Installation + +If you're already running a Fedora Atomic variant, you can rebase to Sediment: + +1. **Rebase to unsigned image** (to install signing keys): + ```bash + rpm-ostree rebase ostree-unverified-registry:ghcr.io/sidusIO/sediment:latest + ``` + +2. **Reboot**: + ```bash + systemctl reboot + ``` + +3. **Rebase to signed image**: + ```bash + rpm-ostree rebase ostree-image-signed:docker://ghcr.io/sidusIO/sediment:latest + ``` + +4. **Reboot again**: + ```bash + systemctl reboot + ``` + +## 🚀 Getting Started + +### First Steps After Installation + +1. **Set up fingerprint authentication** (if supported): + ```bash + just fingerprint + ``` + +2. **Install ASDF version manager** (for managing development tool versions): + ```bash + just asdf + ``` + This installs ASDF into your user space (`~/.asdf`) with Fish shell integration. + +3. **Install JetBrains Toolbox** (for JetBrains IDEs): + ```bash + just jetbrains-toolbox + ``` + +### Available Just Commands + +Sediment uses [just](https://github.com/casey/just) as a command runner. Here are the custom commands available: + +#### Screen Capture +```bash +# Take a screenshot and edit it in swappy +just screenshot-edit + +# Take a screenshot and copy to clipboard +just screenshot + +# Record screen video (saved to ~/Videos/screencapture-{timestamp}.mkv) +just screencapture +``` + +#### Development Tools +```bash +# Install ASDF version manager +just asdf + +# Set up fingerprint authentication +just fingerprint + +# Install JetBrains Toolbox +just jetbrains-toolbox +``` + +Run `just` without arguments to see all available commands, including those inherited from the base Fedora Atomic system. + +## 🛠️ What's Included + +### Pre-installed Software + +- **Shell**: Fish (default shell) +- **Containers**: Docker CE, Distrobox +- **Development**: Kubernetes client (kubectl) +- **Screen Capture**: grim, slurp, swappy, wf-recorder +- **Authentication**: fprintd for fingerprint support + +### Custom Configurations + +- **Sway**: Custom configurations in `/usr/etc/sway/config.d/` + - GNOME Keyring integration (95-gnome-keyring.conf) +- **Environment**: Custom environment variables in `/usr/etc/environment.d/` + - Default shell set to Fish + - GNOME Keyring SSH agent configuration +- **Automatic Updates**: Systemd timer runs every 6 hours after boot + +### Fonts + +**Google Fonts**: +- Roboto +- Open Sans + +**Nerd Fonts**: +- FiraCode +- Hack +- SourceCodePro +- Terminus +- JetBrainsMono +- NerdFontsSymbolsOnly + +## 🔧 Building & Development + +### Prerequisites + +- Podman or Buildah +- Just (command runner) + +### Build the Image Locally + +```bash +# Using buildah +buildah build -t sediment:local -f Containerfile . + +# Using podman +podman build -t sediment:local -f Containerfile . +``` + +### Format Just Files + +```bash +just fmt +``` + +### CI/CD + +Sediment uses GitHub Actions for continuous integration: + +- **Build Workflow**: Automatically builds and publishes container images daily at 17:00 UTC +- **ISO Release**: Generates installation ISOs and publishes them to the `auto-iso` release +- **Image Signing**: All images are signed with Cosign for verification + +## 📚 Useful Links + +### Project Resources +- **GitHub Repository**: [sidusIO/sediment](https://github.com/sidusIO/sediment) +- **Container Registry**: [ghcr.io/sidusio/sediment](https://ghcr.io/sidusio/sediment) +- **ISO Downloads**: [Releases](https://github.com/sidusIO/sediment/releases/tag/auto-iso) + +### Upstream Projects +- **Fedora Atomic Desktops**: https://fedoraproject.org/atomic-desktops/ +- **Fedora Sway Atomic**: https://fedoraproject.org/atomic-desktops/sway/ +- **rpm-ostree**: https://coreos.github.io/rpm-ostree/ +- **Universal Blue**: https://universal-blue.org/ + +### Documentation +- **Sway WM**: https://swaywm.org/ +- **rpm-ostree**: https://coreos.github.io/rpm-ostree/ +- **Distrobox**: https://distrobox.it/ +- **Just**: https://github.com/casey/just + +### Tools & Utilities +- **Fish Shell**: https://fishshell.com/ +- **ASDF**: https://asdf-vm.com/ +- **Docker**: https://docs.docker.com/ + +## 🤝 Contributing + +Contributions are welcome! Feel free to: + +- Open issues for bugs or feature requests +- Submit pull requests with improvements +- Share your configurations and customizations + +Please ensure pull requests follow the existing code style and conventions. + +## 📄 License + +This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details. + +## 💡 Tips & Tricks + +- **Immutable OS**: Remember that `/usr` is read-only. Use `rpm-ostree install` to layer packages, or use Distrobox for development environments. +- **Updates**: Updates happen automatically, but you can manually update with `rpm-ostree update` and reboot. +- **Rollback**: If something goes wrong, rollback to the previous deployment with `rpm-ostree rollback`. +- **Layered Packages**: Check layered packages with `rpm-ostree status`. +- **Customization**: Add your own custom configurations to `/etc` (mutable) or create your own custom image based on Sediment. + +## 🆘 Troubleshooting + +### Fingerprint Reader Not Working +Ensure your device's fingerprint reader is supported by fprintd. Run `fprintd-list` to check available devices. + +### Screen Capture Not Working +Make sure you're running under Wayland (Sway). The capture tools require Wayland. + +### Docker Permission Issues +Add your user to the docker group: +```bash +sudo usermod -aG docker $USER +``` +Then log out and back in for changes to take effect. + +--- + +**Built with ❤️ using Fedora Atomic and rpm-ostree**