Merge pull request #35 from AkihiroSuda/dev

docs: update

Author: AkihiroSuda

.github/workflows/main.yml

@@ -23,7 +23,15 @@ jobs:
       - run: go test -v ./...
       - run: go build ./cmd/usr-lib-apt-methods-oci
       - run: sudo cp -a usr-lib-apt-methods-oci /usr/lib/apt/methods/oci
-      - run: echo "deb [trusted=yes] oci://ghcr.io/akihirosuda/hello-apt-transport-oci:latest /" | sudo tee /etc/apt/sources.list.d/oci.list
+      - run: |
+          sudo tee /etc/apt/sources.list.d/oci.sources <<EOF
+          Types: deb
+          URIs: oci://ghcr.io/akihirosuda/hello-apt-transport-oci:latest
+          Suites: stable
+          Components: main
+          Signed-By: /etc/apt/keyrings/AkihiroSuda.gpg
+          EOF
+      - run: curl -fsSL https://github.com/AkihiroSuda.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/AkihiroSuda.gpg
       - run: sudo apt-get update
       - run: sudo apt-get install hello-apt-transport-oci
       - run: hello-apt-transport-oci

README.md

@@ -2,49 +2,57 @@
 
 `apt-transport-oci` is an `apt-get` plugin to support distributing `*.deb` packages over an OCI registry such as `ghcr.io` .
 
+> [!NOTE]
+> "OCI" here refers to the "[Open Container Initiative](https://opencontainers.org/)", not to the "Oracle Cloud Infrastructure".
+
 ## Motivation
 The motivation is to distribute `*.deb` packages without running a web server but using a popular fully-managed service such as `ghcr.io`.
 
 If GitHub could offer fully-managed apt repo, this plugin wouldn't be needed.
 
-## Usage
 
-- Install the `apt-transport-oci` plugin onto `/usr/lib/apt/methods/oci`:
+## Install
+The `apt-transport-oci` plugin is officially [packaged](https://repology.org/project/apt-transport-oci/versions) in Debian and Ubuntu,
+since Debian 14 and Ubuntu 26.04.
+
+```bash
+sudo apt install apt-transport-oci
 ```
+
+<details><summary>Build from source</summary>
+<p>
+
+```bash
 sudo go build -o /usr/lib/apt/methods/oci ./cmd/usr-lib-apt-methods-oci
 ```
 
-- Create `/etc/apt/sources.list.d/oci.list` with the following content to enable [`oci://ghcr.io/akihirosuda/hello-apt-transport-oci`](https://ghcr.io/akihirosuda/hello-apt-transport-oci) repo:
+</p>
+</details>
+
+## Example
+The following example installs the `hello-apt-transport-oci` package from the [`oci://ghcr.io/akihirosuda/hello-apt-transport-oci`](https://ghcr.io/akihirosuda/hello-apt-transport-oci) repo.
+
+> [!TIP]
+> See [`./examples`](./examples) for how to build and push this package to your own registry.
+
+- Create `/etc/apt/sources.list.d/oci.sources` with the following content:
 ```
-deb [trusted=yes] oci://ghcr.io/akihirosuda/hello-apt-transport-oci:latest /
+Types: deb
+URIs: oci://ghcr.io/akihirosuda/hello-apt-transport-oci:latest
+Suites: stable
+Components: main
+Signed-By: /etc/apt/keyrings/AkihiroSuda.gpg
 ```
 
-- Run `sudo apt-get update && sudo apt-get install hello-apt-transport-oci`
-
-```console
-$ sudo apt-get update
-...
-Get:7 oci://ghcr.io/akihirosuda/hello-apt-transport-oci:latest  Packages [478 B]
-...
-Reading package lists... Done
+- Register a GPG key:
+```bash
+curl -fsSL https://github.com/AkihiroSuda.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/AkihiroSuda.gpg
 ```
 
-```console
-$ sudo apt-get install hello-apt-transport-oci
-Reading package lists... Done
-Building dependency tree... Done
-Reading state information... Done
-The following NEW packages will be installed:
-  hello-apt-transport-oci
-0 upgraded, 1 newly installed, 0 to remove and 1 not upgraded.
-Need to get 1,106 B of archives.
-After this operation, 0 B of additional disk space will be used.
-Get:1 oci://ghcr.io/akihirosuda/hello-apt-transport-oci:latest  hello-apt-transport-oci 0.0 [1,106 B]
-Selecting previously unselected package hello-apt-transport-oci.
-(Reading database ... 249739 files and directories currently installed.)
-Preparing to unpack .../hello-apt-transport-oci_0.0_amd64.deb ...
-Unpacking hello-apt-transport-oci (0.0) ...
-Setting up hello-apt-transport-oci (0.0) ...
+- Run:
+```bash
+sudo apt update
+sudo apt install hello-apt-transport-oci
 ```
 
 - Make sure `hello-apt-transport-oci` is installed
@@ -53,19 +61,16 @@ $ hello-apt-transport-oci
 Hello, apt-transport-oci
 ```
 
-### Hints
+## Hints
 - Create `/root/.docker/config.json` to enable authentication.
 - Non-TLS registry is supported only for 127.0.0.1
 - Troubleshooting: Run `apt-get -o Debug::pkgAcquire::Worker=1 update 2>&1` and grep `FailReason`
 
-## Creating an apt repo
-See [`./examples`](./examples) .
-
 ## Specification
-The spec corresponds to the behavior of `oras push IMAGE FILE1:application/octet-stream FILE2:application/octet-stream ...` (ORAS v0.12).
+The spec corresponds to the behavior of `oras push --image-spec=v1.0 IMAGE FILE1:application/octet-stream FILE2:application/octet-stream ...`.
 
 - An image index MAY have multiple manifests, but all the manifests SHOULD refer to the same set of layers (because `apt-get` itself supports multi-arch repo).
 - A layer MUST have `org.opencontainers.image.title` annotation that corresponds to the file name.
 - A layer SHOULD have one of the following media types:
- - `application/octet-stream`
- - `application/x-binary`
+  - `application/octet-stream`
+  - `application/x-binary`

examples/README.md

@@ -1,42 +1,103 @@
 # Creating an apt repo on an OCI registry
 
 ## Step 1: Create dpkg
-Create `hello-apt-transport-oci_0.0_amd64.deb` from [`helloapt-transport-oci` directory](./hello-apt-transport-oci).
-The easiest way is to use [fpm](https://fpm.readthedocs.io/).
+Create `hello-apt-transport-oci_0.1_all.deb` from [`helloapt-transport-oci` directory](./hello-apt-transport-oci).
 
 ```bash
-sudo gem install fpm
+dpkg-deb --build --root-owner-group hello-apt-transport-oci hello-apt-transport-oci_0.1_all.deb
 ```
 
+## Step 2: Create repository data
+
+Use [aptly](https://www.aptly.info) to create the repository data.
+
 ```bash
-fpm -s dir -t deb -m example@example.com -n hello-apt-transport-oci -v 0.0 ./hello-apt-transport-oci/usr/bin/hello-apt-transport-oci=/usr/bin/hello-apt-transport-oci
+sudo apt-get install aptly
 ```
 
-## Step 2: Create metadata
-Create `Packages` file
-```
-dpkg-scanpackages -m . > Packages
+```bash
+aptly repo create hello-apt-transport-oci
+aptly repo add hello-apt-transport-oci hello-apt-transport-oci_0.1_all.deb
+aptly publish repo -distribution=stable -architectures=all,amd64,arm64 hello-apt-transport-oci
 ```
 
-Hint: to create GPG-signed repo, use [`apt-ftparchive`](https://www.google.com/search?q=apt-ftparchive+gpg) .
+The repository data will be locally published on `~/.aptly/public`.
+
+```console
+$ tree ~/.aptly/public
+/home/USER/.aptly/public
+├── dists
+│   └── stable
+│       ├── Contents-all.gz
+│       ├── Contents-amd64.gz
+│       ├── Contents-arm64.gz
+│       ├── InRelease
+│       ├── main
+│       │   ├── binary-all
+│       │   │   ├── Packages
+│       │   │   ├── Packages.bz2
+│       │   │   ├── Packages.gz
+│       │   │   └── Release
+│       │   ├── binary-amd64
+│       │   │   ├── Packages
+│       │   │   ├── Packages.bz2
+│       │   │   ├── Packages.gz
+│       │   │   └── Release
+│       │   ├── binary-arm64
+│       │   │   ├── Packages
+│       │   │   ├── Packages.bz2
+│       │   │   ├── Packages.gz
+│       │   │   └── Release
+│       │   ├── Contents-all.gz
+│       │   ├── Contents-amd64.gz
+│       │   └── Contents-arm64.gz
+│       ├── Release
+│       └── Release.gpg
+└── pool
+    └── main
+        └── h
+            └── hello-apt-transport-oci
+                └── hello-apt-transport-oci_0.1_all.deb
+
+11 directories, 22 files
+```
 
 ## Step 3: Push to an OCI registry
 Push the deb file and the `Packages` file to an OCI registry (e.g., `ghcr.io`).
 
 The easiest way is to use [ORAS](https://github.com/oras-project/oras) CLI.
 
 ```bash
-curl -fsSL https://github.com/oras-project/oras/releases/download/v0.12.0/oras_0.12.0_linux_amd64.tar.gz | sudo tar Cxzv /usr/local/bin/ oras
+sudo apt-get install oras
 ```
 
 ```bash
 echo YOUR_GITHUB_PERSONAL_ACCESS_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
 ```
 
 ```bash
-oras push ghcr.io/USERNAME/hello-apt-transport-oci:latest hello-apt-transport-oci_0.0_amd64.deb:application/octet-stream Packages:application/octet-stream`
+cd ~/.aptly/public
+find . -type f -printf "%p:application/octet-stream\n" | xargs oras push --image-spec=v1.0 ghcr.io/USERNAME/hello-apt-transport:latest
 ```
 
 - See [GHCR documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) to learn
-how to create a GitHub Personal Access Token (PAT) for `ghcr.io`.
+how to create a [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens) (PAT) for `ghcr.io`.
 - Use GitHub Web UI to make the image public / private.
+
+## Step 4: Tell users the instruction
+
+Tell your users how to install your package:
+
+> - Create `/etc/apt/sources.list.d/oci.sources` with the following content:
+> ```
+> Types: deb
+> URIs: oci://ghcr.io/USERNAME/hello-apt-transport-oci:latest
+> Suites: stable
+> Components: main
+> Signed-By: /etc/apt/keyrings/USERNAME.gpg
+> ```
+>
+> - Register a GPG key:
+> ```bash
+> curl -fsSL https://github.com/USERNAME.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/USERNAME.gpg
+> ```

examples/hello-apt-transport-oci/DEBIAN/control

@@ -0,0 +1,5 @@
+Package: hello-apt-transport-oci
+Version: 0.1
+Architecture: all
+Maintainer: example@example.com
+Description: hello apt-transport-oci