diff --git a/.github/workflows/build-containers.yml b/.github/workflows/build-containers.yml index 3ee71d9..d59efb4 100644 --- a/.github/workflows/build-containers.yml +++ b/.github/workflows/build-containers.yml @@ -2,9 +2,13 @@ name: build-containers on: push: + paths-ignore: + - '**.adoc' tags: - "v*" pull_request: + paths-ignore: + - '**.adoc' workflow_dispatch: workflow_run: workflows: ["add-tag"] diff --git a/README.adoc b/README.adoc index 33a41f7..ff75107 100644 --- a/README.adoc +++ b/README.adoc @@ -1,72 +1,71 @@ -= Tebako Docker containers += Tebako Docker Containers -== Pre-built containers - -This repository contains definitions of Docker containers with a preinstalled -Tebako packaging environment, and provides those built Docker containers. - -Tebako containers offer a streamlined and isolated environment for packaging -applications, ensuring consistency and reproducibility across different -development setups. By using containers, developers can bypass the complexities -of managing multiple dependencies on their local machines. +== What is Tebako? +Tebako is an executable packager designed to simplify the process of packaging applications that rely on an interpretive runtime, making distribution easier. It packages a set of files into a DwarFS file system for read-only purposes. +For more details, visit the https://www.tebako.org[Tebako website]. -== What is Tebako? +== Pre-built Containers -Tebako is an executable packager that simplifies the process of packaging applications -that utilize an interpretive runtime, allowing for easy distribution. +Tebako packages for Linux systems must be created on the same architecture and standard library implementation as the target system. For example: -It packages a set of files into a DwarFS file system for read-only purposes. +- **x86_64/aarch64 packages** require **x86_64/aarch64 systems**, respectively. +- Packages compatible with **GNU/musl Linux** must be created in **GNU/musl environments**. -Please refer to the https://www.tebako.org[Tebako website] for more details. +Installing Tebako on different Linux configurations can be cumbersome, and our testing is limited to a specific set of Ubuntu and Alpine configurations. +== Available Container Tags +Tebako containers are available to support packaging for both GNU and musl target environments. The currently available tags are: -== Available container tags +=== `ubuntu-20.04` -Tebako containers are available with different base images to suit various needs. +This container is based on **Ubuntu 20.04 LTS**, providing an environment for packaging applications for GNU systems that use the https://sourceware.org/glibc[`glibc` implementation of the C standard library]. -The currently available tags are: +The `--patchelf` option enables the creation of packages that are forward-compatible with GNU Linux distributions running GLIBC version 2.31 and above. -`ubuntu-20.04`:: -This container is based on Ubuntu 20.04 LTS (`glibc`), providing a stable and -widely used environment for packaging. +.Minimum versions of GLIBC Linux distributions that support Tebako packages with forward portability +[cols="3", options="header"] +|=== +| Distribution | Minimal Supported Version | GLIBC Version +| Ubuntu | 20.04 (Focal Fossa) | GLIBC 2.31 +| Debian | 11 (Bullseye) | GLIBC 2.31 +| Rocky Linux | 9 | GLIBC 2.34 +| Fedora | 33 | GLIBC 2.32 +| CentOS | 9 | GLIBC 2.34 +| Red Hat Enterprise Linux (RHEL) | 9 | GLIBC 2.34 +| Oracle Linux | 9 | GLIBC 2.34 +|=== -`alpine-3.17`:: -This container is based on Alpine Linux 3.17 (`musl`), offering a smaller image -size. Suitable for those who prefer a minimalistic approach. +=== `alpine-3.17` -Containers are tailored for Tebako packaging, featuring preinstalled Ruby -environments versions 3.2.6 and 3.3.6. +This container is based on **Alpine Linux 3.17**, offering an environment for packaging applications for systems that use the https://musl.libc.org[`musl` implementation of the C standard library]. -Both acontainers are available on the GitHub Container Registry (GHCR) for amd64 and arm64 architectures. +Both containers are available on the **GitHub Container Registry (GHCR)** for **x86_64 (amd64)** and **aarch64 (arm64)** architectures, with multi-architecture manifests. These containers come preinstalled with Tebako packaging environments for Ruby versions **3.2.6** and **3.3.6**. -== Using the Tebako containers +== Using the Tebako Containers === General -There are two primary methods for packaging with Tebako: from inside the -container and from outside using Docker commands. +There are two primary methods for packaging with Tebako: -=== Prerequisites - -* Docker installed on your machine. -* A Ruby application ready for packaging. +1. **From outside the container**: Using Docker commands to package your application without entering the container. +2. **From inside the container**: Interactively working within the container to package your application. +=== Prerequisites -=== Package using an ephemeral container +- Docker installed on your machine. +- A Ruby application ready for packaging. -You can also package your application from outside the container by running a -single Docker command. +=== From Outside the Container -This command mounts your workspace into the container and runs the -`tebako press` command, specifying: +You can package your application from outside the container by running a single Docker command. This command mounts your workspace into the container and executes the `tebako press` command, specifying: -* application root -* entry point -* output location -* Ruby version +- Application root +- Entry point +- Output location +- Ruby version [source,sh] ---- @@ -75,11 +74,10 @@ $ docker run -v :/mnt/w \ tebako press ---- -.Packaging `fontist` with an ephemeral container +.Packaging the `fontist` Gem from Outside the Container [example] ==== -A Ruby application called `fontist` inside `fontist/` under the current -directory, can be packaged into `./fontist-package` using the following command. +To package the https://github.com/fontists/fontist[`fontist` gem], a Ruby application for managing fonts, located in the `fontist/` directory under the current working directory, use the following command: [source,sh] ---- @@ -89,11 +87,11 @@ docker run -v $PWD:/mnt/w \ ---- ==== -=== Package using a persistent container +=== From Inside the Container To package your application from inside the Tebako container, follow these steps: -. Pull the Tebako container image: +1. Pull the Tebako container image: + [source,sh] ---- @@ -102,33 +100,30 @@ $ docker pull ghcr.io/tamatebako/tebako-:latest + Replace `` with the desired container tag (e.g., `ubuntu-20.04` or `alpine-3.17`). -. Start and enter the container interactively: +2. Start and enter the container interactively: + [source,sh] ---- $ docker run -it --rm -v :/mnt/w ghcr.io/tamatebako/tebako-:latest bash ---- + -Replace `` with the appropriate tag and `` -with the path to your application folder. +Replace `` with the appropriate tag and `` with the path to your application folder. -. Once inside, run the `tebako press` command: +3. Once inside the container, run the `tebako press` command: + [source,sh] ---- $ tebako press ---- - -.Packaging `fontist` with a persistent container +.Packaging the `fontist` Gem from Inside the Container [example] ==== -A Ruby application called `fontist` inside `fontist/` under the current -directory, can be packaged into `./fontist-package` using the following command. +To package the https://github.com/fontists/fontist[`fontist` gem], located in the `fontist/` directory under the current working directory, use the following commands: [source,sh] ---- -# Starting a persistent container +# Start and enter the container $ docker run -it --rm -v $PWD:/mnt/w ghcr.io/tamatebako/tebako-:latest bash # Run this after entering the container @@ -136,6 +131,19 @@ $ tebako press --root=/mnt/w/fontist --entry-point=fontist --output=/mnt/w/fonti ---- ==== +`Gemspec` files often specify the files included in the gem using `git ls-files`. When packaging from inside the container, the container's instance of `git` will be used to resolve these files. + +If you use a mounted host directory for packaging, the container's instance of `git` will not have access to it by default. To resolve this, you must alter the container's configuration by running the following command before packaging: + +[source,sh] +---- +git config --global --add safe.directory +---- + +However, to avoid this additional setup, we recommend packaging **from outside the container** instead of modifying the container's configuration as described above. + +Packaging from inside the container is primarily designed to support CI environments like GitHub Actions (GHA) or Cirrus CI. It provides a complete packaging environment that +does not require any additional installations, making it ideal for automated workflows. == License