diff --git a/README.md b/README.md index 2600b96..264ac03 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,71 @@ -# ucore-main +# ucore -[![build-ucore](https://github.com/bsherman/ucore-main/actions/workflows/build.yml/badge.svg)](https://github.com/bsherman/ucore-main/actions/workflows/build.yml) - -A WIP common main image for all other Ucore images. +[![build-ucore](https://github.com/ublue-os/ucore/actions/workflows/build.yml/badge.svg)](https://github.com/ublue-os/ucore/actions/workflows/build.yml) ## What is this? -This is an OCI image of [Fedora CoreOS](https://getfedora.org/coreos/) with quality of life improvments. +You should be familiar with [Fedora CoreOS](https://getfedora.org/coreos/), as this is an OCI image of CoreOS with "batteries included". More specifically, it's an opinionated, custom CoreOS image built daily with some commonly installed tools, pre-installed. The idea is to make a lightweight server image including most used services or the building blocks to host them. -### WARNING: not yet tested +WARNING: This image has **not** been heavily tested, though the underlying components have. Please take a look at the included modifications and help test if this project interests you. ## Features -- Start with Fedora CoreOS image -- add some packages: - - cockpit - - distrobox - - docker-compose & podman-compose - - duperemove - - tailscale and wireguard-tools -- remove some packages: +- Starts with a [Fedora CoreOS image](https://quay.io/repository/fedora/fedora-coreos?tab=tags) +- Removes these stock packages: - toolbox - zincati +- Adds the following: + - [cockpit](https://cockpit-project.org) + - [distrobox](https://github.com/89luca89/distrobox) + - [duperemove](https://github.com/markfasheh/duperemove) + - moby-engine, docker-compose and podman-compose + - [tailscale](https://tailscale.com) and [wireguard-tools](https://www.wireguard.com) - Sets automatic staging of updates for system -- 60 second service stop timeout for reasonably fast shutdowns +- Sets 60 second service stop timeout for reasonably fast shutdowns +- Enables password based SSH auth (required for locally running cockpit web interface) -This image should be suitable for use on bare metal or in a virtual machines where you wish to run containerized workloads. It uses sign -ificantly less disk space than [ucore-hci](https://github.com/bsherman/ucore-hci), but check that out if you need to host virtual machines or run ZFS. +One can layer packages directly on a machine running UCore or use this image as a base for further customized OCI builds. -One can also layer packages directly on a machine running this or use this image as a base for a further customized OCI. - -Note: cockpit-ws runs as a podman container, not a direct systemd service. This image pre-configures it to run, but it can be disabled: +Note: per [cockpit instructions](https://cockpit-project.org/running.html#coreos) the cockpit-ws RPM is **not** installed, rather it is available as a podman container. This image has pre-configured cockpit to run on system boot, but it can be disabled: sudo systemctl disable --now cockpit.service +This image should be suitable for use on bare metal or in a virtual machines where you wish to run containerized workloads. -## Usage +## Tips and Tricks -To rebase an Fedora CoreOS machine to the latest release (stable): +These images are immutable, you can't, and really shouldn't, install packages like in a mutable "normal" distribution. - sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/bsherman/ucore-main:stable +CoreOS expects the user to run services using [podman](https://podman.io). `moby-engine`, the free Docker implementation, is installed for those who desire docker instead of podman. + +NOTE: CoreOS [cautions against](https://docs.fedoraproject.org/en-US/fedora-coreos/faq/#_can_i_run_containers_via_docker_and_podman_at_the_same_time) running podman and docker containers at the same time. + +Users may use [distrobox](https://github.com/89luca89/distrobox) to run images of mutable distributions where applications can be installed with traditional package managers. This may be useful for installing interactive utilities such has `htop`, `nmap`, etc. As stated above, however, *services* should run as containers. + +It's a good idea to become familar with the [Fedora CoreOS Documentation](https://docs.fedoraproject.org/en-US/fedora-coreos/) as well as the [CoreOS rpm-ostree docs](https://coreos.github.io/rpm-ostree/). Note especially, this image is only possible due to [ostree native containers](https://coreos.github.io/rpm-ostree/container/). + +## How to Install + +### Prerequsites + +This image is not currently avaialable for direct install. The user must follow the [CoreOS installation guide](https://docs.fedoraproject.org/en-US/fedora-coreos/bare-metal/). Note there are varying methods of installation for bare metal, cloud providers, and virtualization platforms. + +All CoreOS installation methods require the user to [produce an Ignition file](https://docs.fedoraproject.org/en-US/fedora-coreos/producing-ign/). This Ignition file should, at mimimum, set a password and SSH key for the default user (default username is `core`). + + +### Install and Rebase + +To rebase an Fedora CoreOS machine to the latest UCore (stable): + +1. Install CoreOS via [desired installation method](https://docs.fedoraproject.org/en-US/fedora-coreos/bare-metal/) +1. After you reboot you should [pin the working deployment](https://docs.fedoraproject.org/en-US/fedora-silverblue/faq/#_how_can_i_upgrade_my_system_to_the_next_major_version_for_instance_rawhide_or_an_upcoming_fedora_release_branch_while_keeping_my_current_deployment) which allos you to rollback if required. +1. SSH to the freshly installed CoreOS system and rebase the OS: + + sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/ucore:stable ## Verification These images are signed with sisgstore's [cosign](https://docs.sigstore.dev/cosign/overview/). You can verify the signature by downloading the `cosign.pub` key from this repo and running the following command: - cosign verify --key cosign.pub ghcr.io/bsherman/ucore-main \ No newline at end of file + cosign verify --key cosign.pub ghcr.io/ublue-os/ucore \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..d46f345 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,16 @@ +# Expectations + +This is a volunteer-run project and is mostly creating images from existing Fedora CoreOS packages. +If you've found an issue with something in one of these repositories you'd need to see if that package +comes from CoreOS or from a third party resource and report the issue there. +The images build every day and automatically slipstream the changes from CoreOS into the final image. + +# Security Response +If the issue is with something you've found in CoreOS then checkout this information from the +[CoreOS security.md](https://github.com/coreos/.github/blob/master/SECURITY.md): +>If you've found a security issue that you'd like to disclose confidentially please contact +Red Hat's Product Security team. Details at https://access.redhat.com/security/team/contact + +# License +Most repositories are licensed under the Apache License, Version 2.0. Some components may be licensed +differently - consult individual repositories for more.