Skip to content

Commit 2b7f15c

Browse files
committed
Add license badges and build instructions to README
Enhance README with essential information for users and contributors: - Add GPL v2 license badge for clear licensing visibility - Add GitHub Release badge to highlight latest version - Add "Getting Images" section documenting: - Pulling from container registry (:latest, :edge, version tags) - Loading OCI tarballs from releases (supports issue #21 fix) - Usage for air-gapped environments - Add "Building from Source" section with: - Prerequisites and system requirements - Step-by-step build instructions with git submodules - List of all available containers (system, ntpd, nftables, httpd, neofetch) - Multi-architecture support (amd64/arm64) - Customization guide using menuconfig - Link to CONTRIBUTING.md These additions make the project more accessible by documenting both pre-built image usage and source builds, directly supporting the recent :latest tagging and tarball compatibility improvements. Signed-off-by: Joachim Wiberg <[email protected]>
1 parent 814c689 commit 2b7f15c

File tree

1 file changed

+98
-0
lines changed

1 file changed

+98
-0
lines changed

README.md

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
# curiOS — slim, curated containers
44

5+
[![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
6+
[![GitHub Release](https://img.shields.io/github/v/release/kernelkit/curiOS)](https://github.com/kernelkit/curiOS/releases)
7+
58
**Lightweight • Secure • Purpose-Built**
69

710
*curiOS* delivers ultra-slim, curated container images optimized for
@@ -149,6 +152,101 @@ docker run --rm -v /etc/os-release:/etc/os-release:ro ghcr.io/kernelkit/curios-n
149152
docker run --rm -i -t --entrypoint /bin/bash ghcr.io/kernelkit/curios-neofetch:latest
150153
```
151154

155+
## Getting Images
156+
157+
### From Container Registry
158+
159+
The easiest way to use curiOS is pulling pre-built images from the
160+
[KernelKit Container Registry][2]:
161+
162+
```bash
163+
# Pull the latest stable release
164+
docker pull ghcr.io/kernelkit/curios-nftables:latest
165+
166+
# Or pull a specific version
167+
docker pull ghcr.io/kernelkit/curios-nftables:1.2.3
168+
169+
# Or pull the bleeding edge
170+
docker pull ghcr.io/kernelkit/curios-nftables:edge
171+
```
172+
173+
### From Release Tarballs
174+
175+
Alternatively, download OCI tarballs from [GitHub Releases](https://github.com/kernelkit/curiOS/releases)
176+
and load them with `podman` or `docker`:
177+
178+
```bash
179+
# Download release tarball
180+
wget https://github.com/kernelkit/curiOS/releases/download/v1.2.3/curios-nftables-oci-amd64-v1.2.3.tar.gz
181+
182+
# Extract and load with podman
183+
tar xzf curios-nftables-oci-amd64-v1.2.3.tar.gz
184+
cd curios-nftables-oci-amd64-v1.2.3
185+
podman load < index.json
186+
187+
# Or with docker
188+
docker load < index.json
189+
```
190+
191+
This method is useful for air-gapped environments or when you want to verify
192+
the tarball checksum before loading.
193+
194+
## Building from Source
195+
196+
curiOS uses [Buildroot][0] as its build system. To build a container from source:
197+
198+
### Prerequisites
199+
200+
- Linux build system (Ubuntu, Debian, Fedora, etc.)
201+
- Standard development tools: `gcc`, `make`, `git`
202+
- At least 4GB of free disk space
203+
204+
### Build Steps
205+
206+
```bash
207+
# Clone the repository
208+
git clone https://github.com/kernelkit/curiOS.git
209+
cd curiOS
210+
git submodule update --init --recursive
211+
212+
# Configure for your target (e.g., nftables for amd64)
213+
make nftables_amd64_defconfig
214+
215+
# Build (this will take a while on first run)
216+
make
217+
218+
# The resulting OCI image will be in output/images/
219+
cd output/images
220+
ls -lh rootfs-oci/
221+
222+
# Load into podman or docker
223+
podman load < rootfs-oci
224+
```
225+
226+
### Available Containers
227+
228+
You can build any of these containers by replacing `nftables` in the commands above:
229+
230+
- `system` - Full-featured development environment
231+
- `ntpd` - NTP time synchronization
232+
- `nftables` - Firewall container
233+
- `httpd` - Lightweight web server
234+
- `neofetch` - System information display
235+
236+
Each container supports both `amd64` and `arm64` architectures (e.g.,
237+
`nftables_amd64_defconfig` or `nftables_arm64_defconfig`).
238+
239+
### Customizing Containers
240+
241+
To customize a container:
242+
243+
1. Start with an existing defconfig: `make nftables_amd64_defconfig`
244+
2. Modify the configuration: `make menuconfig`
245+
3. Save your changes: `make savedefconfig`
246+
4. Build: `make`
247+
248+
For more details, see [CONTRIBUTING.md](.github/CONTRIBUTING.md).
249+
152250
## Origin & References
153251

154252
curiOS is a wrapper around [Buildroot][0] for creating container images for

0 commit comments

Comments
 (0)