Alpine Ports Tools

A simple wrapper for Podman that manipulates and builds Alpine Linux ports.

Requirements

• Podman
• A compatible shell
  • bash
  • posix sh
  • busybox ash
  • dash

Usage

To get started simply source the functions.sh file into your shell by running . ./functions.sh.

This will add the following commands to your shell session:

• portstool - The main utility.
• portssh - Allow you to enter an Alpine Linux shell for debugging purposes.
• portsprep - Allows you to manually rebuild the container image and the directory layout for work/.
• portsexit - Removes the commands from your shell.
• portsclean - Removes the commands from your shell and removes the Podman image.

The utility supports the following operations:

• build -- Builds port(s) from tree
• clone -- Clones a ports tree from a git repo
• checksum -- Update checksum on selected port
• keygen -- Generate package signing keys

Note that limitations of some shells may require you to source functions.sh twice so we can correctly set up the state of the utility. You will be warned if this is necessary.

Getting Started

Before doing anything, you need to generate a pair of signing keys to sign your releases with using portstool keygen.

Running the keygen command without arguments will use the following defaults:

• Key Name: build (can be changed with -k)
• Key Length: 4096 (can be changed with -b)

Example Workflow: Building a Port

To build a port, you must do the following:

1. Use the clone subcommand to clone the ports tree, or manually copy it into the work/ports directory
   • portstool clone https://git.example.com/exampleorg/ports.git
   • Or cp -ar ~/ports <ports tool directory>/work/ports (make sure you run portsprep once so this is created)
2. Build the port
   • portstool build exampletool

Most subcommands support additional switches which can be used to tweak various steps.

The resulting package will be stored in work/packages. You must copy the appropriate public key from work/keys to the target machine before installing it.

Example Workflow: Editing a Port

To edit an existing port prior to building it, do the following:

1. Use the clone subcommand to clone the ports tree, or manually copy it into the work/ports directory
   • portstool clone https://git.example.com/exampleorg/ports.git
   • Or cp -ar ~/ports <ports tools directory>/work/ports (if the work directory does not already exist, run portsprep to create it.)
2. Make any desired changes to the port in the work/ports directory
3. If necessary, regenerate the checksums using the checksum subcommand
   • portstool checksum exampletool
4. Build the port
   • portstool build exampletool

Building against a different version of Alpine Linux

You can build against a different version of Alpine by editing ARG VERSION=3.21 on line 1 of src/Containerfile to the desired version, then running portsprep.

Roadmap

• Allow a default ports tree to be selected (if multiple exist)
• Allow a default signing key to be selected (if multiple exist)
• Implement version switching without having to edit Containerfile
• Add support for git ssh remotes
• Add support for git authentication
• Add pull tool to update existing ports tree
• Add checkout tool to switch to different branches or tags on tree.
• Remove dependency on Docker Hub
• Automated testing of all components