feat: add samples for packaging using docker image 'inside' and 'by' containers

.github/workflows/build-containers.yml

@@ -2,9 +2,6 @@ name: build-containers
 
 on:
   push:
-#    branches: [ main ]
-#    paths-ignore:
-#      - '**.adoc'
     tags:     [ 'v*' ]
   pull_request:
   workflow_dispatch:
@@ -16,7 +13,7 @@ concurrency:
 jobs:
   build-containers:
     name: ${{ matrix.container }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     permissions:
       contents: read
       packages: write
@@ -38,16 +35,32 @@ jobs:
           username: tamatebako
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          # list of Docker images to use as base name for tags
+          images: |
+            name/app
+            ghcr.io/username/app
+          # generate Docker tags based on the following events/attributes
+          tags: |
+            type=schedule
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha
+
       - name: Build and push Docker image
         uses: docker/build-push-action@v6
         with:
           context: .
           file: ./${{ matrix.container }}.Dockerfile
           push: ${{ contains(github.ref, 'refs/tags/v') }}
-          tags: ghcr.io/tamatebako/tebako-${{ matrix.container }}
-          labels: |
-            latest
-            "org.opencontainers.image.source=${{ github.repositoryUrl }}"
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
 
       - name: Purge old versions
         if: contains(github.ref, 'refs/tags/v')
@@ -57,4 +70,73 @@ jobs:
           package-name: 'tebako-${{ matrix.container }}'
           package-type: 'container'
           min-versions-to-keep: 1
-          delete-only-untagged-versions: 'true'
+          delete-only-untagged-versions: 'true'
+
+  test-packaging-in-container:
+    name: Package ${{ matrix.gem }} in ${{ matrix.container }} with Ruby ${{ matrix.package_ruby_ver }}
+    if: contains(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-20.04
+    needs: build-containers
+    strategy:
+      fail-fast: false
+      matrix:
+        gem:
+          - 'fontist'
+        container:
+          - 'ubuntu-20.04'
+          - 'alpine-3.17'
+        package_ruby_ver:
+          - '3.1.6'
+          - '3.2.3'
+    container:
+      image: ghcr.io/tamatebako/tebako-${{ matrix.container }}:latest
+
+    steps:
+    - name: Checkout fontist
+      uses: actions/checkout@v4
+      with:
+        repository: fontist/fontist
+        path: ${{github.workspace}}/fontist
+
+    - name: Package fontist
+      run: tebako press --root=fontist --entry-point=fontist --output=fontist-package --Ruby=${{ matrix.package_ruby_ver }}
+
+    - name: Run smoke test
+      run: ./fontist-package help
+
+  test-packaging-by-container:
+    name: Package ${{ matrix.gem }} by ${{ matrix.container }} container with Ruby ${{ matrix.package_ruby_ver }}
+    if: contains(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-20.04
+    needs: build-containers
+    strategy:
+      fail-fast: false
+      matrix:
+        gem:
+          - 'fontist'
+        container:
+          - 'ubuntu-20.04'
+          - 'alpine-3.17'
+        package_ruby_ver:
+          - '3.1.6'
+          - '3.2.3'
+
+    steps:
+    - name: Checkout fontist
+      uses: actions/checkout@v4
+      with:
+        repository: fontist/fontist
+        path: ${{github.workspace}}/fontist
+
+    - name: Package fontist
+      run: |
+        docker run -v ${{github.workspace}}:/mnt/w -t ghcr.io/tamatebako/tebako-${{ matrix.container }}:latest \
+                   tebako press --root=/mnt/w/fontist --entry-point=fontist --output=/mnt/w/fontist-package --Ruby=${{ matrix.package_ruby_ver }}
+
+    - name: Run smoke test Ubuntu
+      if: contains(matrix.container, 'ubuntu')
+      run: ./fontist-package help
+
+    - name: Run smoke test Alpine
+      if: contains(matrix.container, 'alpine')
+      run:  docker run -t alpine:latest ./fontist-package help

README.adoc

@@ -1,6 +1,85 @@
 == Purpose
 
 Tebako is an executable packager. It packages a set of files into a DwarFS file
-system for read-only purposes.
+system for read-only purposes. 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.
+
+The available containers are tailored for Tebako packaging, featuring preinstalled Ruby environments versions 3.1.6 and 3.2.4.
 
 This project contains definitions of docker containers with preinstalled Tebako packaging environment.
+
+= Packaging with Tebako Container
+
+This document describes how to package applications using the Tebako container. Tebako simplifies the process of packaging Ruby applications,
+allowing for easy distribution. There are two primary methods for packaging with Tebako: from inside the container and from outside using Docker commands.
+
+== Available Container Tags
+
+Tebako containers are available with different base images to suit various needs. The currently available tags are:
+
+* `ubuntu-20.04`: This tag is based on Ubuntu 20.04 LTS, providing a stable and widely used environment for packaging.
+* `alpine-3.17`: For those who prefer a minimalistic approach, this tag is based on Alpine Linux 3.17, offering a smaller image size.
+
+== Prerequisites
+
+* Docker installed on your machine.
+* A Ruby application ready for packaging.
+
+== Packaging from Inside the Container
+
+To package your application from inside the Tebako container, follow these steps:
+
+. Pull the Tebako container image:
++
+[source,sh]
+----
+docker pull ghcr.io/tamatebako/tebako-<container_tag>:latest
+----
++
+Replace `<container_tag>` with the desired tag (e.g., `ubuntu-20.04` or `alpine-3.17`).
+
+. 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
+----
++
+Again, replace `<container_tag>` with the appropriate tag and <application_folder> with the path to your application folder.
+
+. Once inside, run the `tebako press` command:
++
+[source,sh]
+----
+tebako press <tebako press parameters>
+----
+
+For example, assuming that you have a Ruby application in the `fontist` folder of the current folder, you can package it to ./fontist-package using the following command:
+[source,sh]
+----
+docker run -it --rm -v $PWD:/mnt/w ghcr.io/tamatebako/tebako-<container_tag>:latest bash
+# Inside the container:
+tebako press --root=/mnt/w/fontist --entry-point=fontist --output=/mnt/w/fontist-package --Ruby=3.2.4
+----
++
+
+== Packaging from Outside the Container
+
+You can also package your application from outside the container by running a single Docker command.
+This command mounts the GitHub workspace into the container and runs the `tebako press` command, specifying the application root, entry point, output location, and Ruby version.
+
+[source,sh]
+----
+docker run -v <application_folder>:/mnt/w -t ghcr.io/tamatebako/tebako-${{ matrix.container }}:latest \
+                   tebako press <tebako press parameters>
+----
++
+
+For example, assuming that you have a Ruby application in the `fontist` folder of the current folder, you can package it to ./fontist-package using 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.4
+----
++

alpine-3.17.Dockerfile

@@ -51,6 +51,7 @@ ENV CXX=clang++
 
 # So we are running as root, HOME=/root, tebako prefix (default) /root/.tebako
 
+ENV TEBAKO_PREFIX=/root/.tebako
 COPY test /root/test
 
 # Create packaging environment for Ruby 3.1.6, 3.2.4
@@ -62,5 +63,5 @@ RUN gem install tebako && \
     tebako press -R 3.2.4 -r /root/test -e tebako-test-run.rb -o ruby-3.2.4-package && \
     rm ruby-*-package
 
-ENV PS1=PS1="\[\]\[\e]0;\u@\h: \w\a\]${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ \[\]"
+ENV PS1="\[\]\[\e]0;\u@\h: \w\a\]${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ \[\]"
 CMD ["bash"]

ubuntu-20.04.Dockerfile

@@ -55,6 +55,7 @@ RUN /opt/tools/tools.sh install_cmake && \
 
 # So we are running as root, HOME=/root, tebako prefix (default) /root/.tebako
 
+ENV TEBAKO_PREFIX=/root/.tebako
 COPY test /root/test
 
 # Create packaging environment for Ruby 3.1.6, 3.2.4
@@ -66,5 +67,5 @@ RUN gem install tebako && \
     tebako press -R 3.2.4 -r /root/test -e tebako-test-run.rb -o ruby-3.2.4-package && \
     rm ruby-*-package
 
-ENV PS1=PS1="\[\]\[\e]0;\u@\h: \w\a\]${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ \[\]"
+ENV PS1="\[\]\[\e]0;\u@\h: \w\a\]${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ \[\]"
 CMD ["bash"]