Skip to content

Commit

Permalink
doc: update README, address #40
Browse files Browse the repository at this point in the history
  • Loading branch information
@maxirmx
maxirmx committed Jan 26, 2025
1 parent 0da3f22 commit a4d8211
Showing 1 changed file with 153 additions and 54 deletions.
207 changes: 153 additions & 54 deletions README.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,72 +1,162 @@
= Tebako Docker containers
= Tebako Docker Containers

== Pre-built containers
== 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].

== Pre-built Containers

Tebako packages for Linux systems must be created on the same architecture and standard library implementation as the target system. For example:

- **x86_64/aarch64 packages** require **x86_64/aarch64 systems**, respectively.
- Packages compatible with **GNU/musl Linux** must be created in **GNU/musl environments**.

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

This repository contains definitions of Docker containers with a preinstalled
Tebako packaging environment, and provides those built Docker containers.
Tebako containers are available to support packaging for both GNU and musl target environments. The currently available tags are:

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.
=== `ubuntu-20.04`

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 `--patchelf` option enables the creation of packages that are forward-compatible with GNU Linux distributions running GLIBC version 2.31 and above.

.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**, offering an environment for packaging applications for systems that use the https://musl.libc.org[`musl` implementation of the C standard library].

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

=== General

There are two primary methods for packaging with Tebako:

1. **From inside the container**.
2. **From outside the container** using Docker commands.

=== Prerequisites

- Docker installed on your machine.
- A Ruby application ready for packaging.

=== Package Using an Ephemeral Container

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

[source,sh]
----
$ docker run -v <application_folder>:/mnt/w \
-t ghcr.io/tamatebako/tebako-${{ container_tag }}:latest \
tebako press <tebako press parameters>
----

.Packaging `fontist` with an Ephemeral Container
[example]
====
To package a Ruby application called `fontist` located in the `fontist/` directory under the current working directory, use the following command:
[source,sh]
----
docker run -v $PWD:/mnt/w \
-t ghcr.io/tamatebako/tebako-ubuntu-20.04:latest \
tebako press --root=/mnt/w/fontist --entry-point=fontist --output=/mnt/w/fontist-package --Ruby=3.2.6
----
====

=== Package Using a Persistent Container

= Tebako Docker Containers

== What is Tebako?

Tebako is an executable packager that simplifies the process of packaging applications
that utilize an interpretive runtime, allowing for easy distribution.
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.

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].

Please refer to the https://www.tebako.org[Tebako website] for more details.
== Pre-built Containers

Tebako packages for Linux systems must be created on the same architecture and standard library implementation as the target system. For example:

- **x86_64/aarch64 packages** require **x86_64/aarch64 systems**, respectively.
- Packages compatible with **GNU/musl Linux** must be created in **GNU/musl environments**.

== Available container tags
Installing Tebako on different Linux configurations can be cumbersome, and our testing is limited to a specific set of Ubuntu and Alpine configurations.

Tebako containers are available with different base images to suit various needs.
== Available Container Tags

The currently available tags are:
Tebako containers are available to support packaging for both GNU and musl target environments. The currently available tags are:

`ubuntu-20.04`::
This container is based on Ubuntu 20.04 LTS (`glibc`), providing a stable and
widely used environment for packaging.
=== `ubuntu-20.04`

`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.
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].

Containers are tailored for Tebako packaging, featuring preinstalled Ruby
environments versions 3.2.6 and 3.3.6.
The `--patchelf` option enables the creation of packages that are forward-compatible with GNU Linux distributions running GLIBC version 2.31 and above.

Both acontainers are available on the GitHub Container Registry (GHCR) for amd64 and arm64 architectures.
.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
|===

== Using the Tebako containers
=== `alpine-3.17`

=== General
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].

There are two primary methods for packaging with Tebako: from inside the
container and from outside using Docker commands.
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**.

=== Prerequisites
== Using the Tebako Containers

* Docker installed on your machine.
* A Ruby application ready for packaging.
=== General

There are two primary methods for packaging with Tebako:

=== Package using an ephemeral container
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.

You can also package your application from outside the container by running a
single Docker command.
=== Prerequisites

This command mounts your workspace into the container and runs the
`tebako press` command, specifying:
- Docker installed on your machine.
- A Ruby application ready for packaging.

* application root
* entry point
* output location
* Ruby version
=== From Outside the Container

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

[source,sh]
----
Expand All @@ -75,11 +165,10 @@ $ docker run -v <application_folder>:/mnt/w \
tebako press <tebako press parameters>
----

.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]
----
Expand All @@ -89,11 +178,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]
----
Expand All @@ -102,40 +191,50 @@ $ docker pull ghcr.io/tamatebako/tebako-<container_tag>:latest
+
Replace `<container_tag>` 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 <application_folder>:/mnt/w ghcr.io/tamatebako/tebako-<container_tag>:latest bash
----
+
Replace `<container_tag>` with the appropriate tag and `<application_folder>`
with the path to your application folder.
Replace `<container_tag>` with the appropriate tag and `<application_folder>` 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 <tebako press parameters>
----


.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-<container_tag>:latest bash
# Run this after entering the container
$ tebako press --root=/mnt/w/fontist --entry-point=fontist --output=/mnt/w/fontist-package --Ruby=3.2.6
----
====

`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 <source>
----

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

Expand Down

0 comments on commit a4d8211

Please sign in to comment.