Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ArtifactsRegistry TypesGetting Started

Wolfi

Create a Wolfi registry, generate an identity token, then publish and install private Wolfi Linux packages with apk using the --allow-untrusted flag.

Use a Wolfi registry to host private Wolfi Linux packages. Self-published indexes are unsigned, so apk commands against this registry require the --allow-untrusted flag unless you configure a signing key.

What you will learn from this topic

In this quickstart, you will:

  • Create a registry in Harness Artifacts.

  • Publish a package to the registry.

  • Install the package from the registry, and confirm that it works.

Before you begin

  • Install Alpine Package Keeper (apk) on your local machine.

  • Install curl. You use it to publish packages to your registry.

  • Make sure you have access to a Harness account with permission to create registries and connectors.

Create a Wolfi Registry

To create a Wolfi Registry, perform the following steps:

  1. In Artifact Registry, select Registries.

  2. Select + Create Registry.

  3. Specify the Registry name.

Registry name criteria

The registry name must start with a letter, can only contain lowercase alphanumerics, _, ., and -, and must be unique to your Harness account.

  1. Optionally, add a Description.

  2. Choose visibility between Public and Private. The default is Private.

  3. Select Wolfi as the Registry type.

  4. Click Save.

  5. Select Create to finalize.

RSA Signing Key

Optionally, you can attach an RSA Signing Key so Harness signs the repository index and clients can verify packages without --allow-untrusted.

To create or import a key, attach it to your registry, and configure clients, go to Set up signing keys.

Upstream proxy configuration (optional)

An upstream proxy allows your registry to fetch Wolfi packages from an external source when they are not available locally. The default upstream is the Wolfi OS package repository, https://packages.wolfi.dev/os.

Create upstream proxy

To create an upstream proxy, perform the following steps:

  1. In Artifact Registry, select Registries.

  2. Select the drop-down next to + Create Registry and select Upstream Proxy.

  3. Specify the Registry name.

  4. Optionally, add a Description.

  5. Choose visibility between Public and Private. The default is Private.

  6. Select Wolfi as the Registry type.

  7. Select the Source: Wolfi Linux or Custom.

    • If you select Custom, specify the Remote registry URL.

Remote registry URL

The URL must point to the parent of the architecture folders, for example https://packages.wolfi.dev/os, where https://packages.wolfi.dev/os/x86_64/ contains the package indexes. If you use another Wolfi mirror or private repository, confirm the path ends at that parent level, not at an architecture subdirectory.

  1. Select the Authentication method. The default is Anonymous for the public Wolfi Linux mirror.

    • Username and password: Specify the username and password. Use an existing secret, or create a new secret by specifying the Name and entering the Secret text.

    • Anonymous: No credentials required.

  2. Select Create to finalize.

Configure the upstream proxy in your registry

To configure the upstream proxy in your registry, perform the following steps:

  1. In Artifact Registry, select an existing Wolfi Artifact.

  2. Go to the Configuration tab.

  3. Select Edit in the Upstream proxy section.

  4. Click + Add upstream proxy.

  5. Select the required proxy from the list.

  6. Click Apply.

  7. Select Update to finalize.

Upstream proxy caching

If a package is not found in your Harness registry, the upstream proxy fetches it from the remote source and caches it.

Wolfi client setup

In your Wolfi Artifact, select Set Up Client. The dialog gives you an identity token, then setup instructions for apk.

Generate an identity token

An identity token serves as the password for authenticating with the registry.

  1. In your Wolfi Artifact, select Set Up Client.

  2. Select Generate Token.

  3. Select an Expiration for the token:

    • 30 Days

    • 90 Days

    • 180 Days

    • Custom

  4. Copy the token. You use it in the following steps in place of <IDENTITY_TOKEN>.

Token expiration

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.

Configure the client

Configure apk to use the registry, then publish and install packages. Replace the values in angle brackets with your own values.

1. Configure the apk repository

Add the registry to /etc/apk/repositories:

URL-encode the @ in your email address as %40.

Refresh the index (allow untrusted indexes):

2. Publish a package

Upload a built .apk file to the registry. The .PKGINFO inside the package supplies the package name, version, and architecture:

3. Install a package

Install the package with apk:

Setup verification

Confirm that your registry serves the package you published. To verify your setup, perform the following steps:

  1. On a host with no cached index for this registry, run apk update --allow-untrusted, then install the package you published with apk add --allow-untrusted <ARTIFACT_NAME>=<VERSION>.

  2. Confirm that apk downloaded the package from your Harness registry address, which is shown in Set Up Client.

  3. In Harness, open your registry and confirm that the package and version appear in the package list.

If a step fails, go to Troubleshooting to resolve common authentication and resolution issues before you retry.

Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step publishes a built .apk file with the version tag embedded in the filename. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

Troubleshooting

`apk update --allow-untrusted` fails with `401` or `403`

Check that the username and identity token in your /etc/apk/repositories entry match the registry address and token shown in Set Up Client, and that the @ in your email address is URL-encoded as %40. If the token expired or was revoked, generate a new one and update the repository line.

`apk add` fails with an untrusted signature error

Self-published indexes in Artifacts are unsigned. Run apk update and apk add with the --allow-untrusted flag. To configure an RSA signing key for the registry, go to Set up signing keys.

A publish with `curl --request PUT` returns `409 Conflict`

Package versions are immutable after publish. Use a new package version, or delete the existing version only if your registry retention and lifecycle policies allow it.

`apk add` cannot find the package or reports unsatisfiable constraints

Check that <ARTIFACT_NAME> and <VERSION> match the values from the .PKGINFO of the package you published, and that <ACCOUNT_ID> and <REGISTRY_NAME> in your repository URL match the registry you published to.

Set Up Client does not show a publish step

Publishing is available only on a virtual Wolfi registry. An upstream proxy registry is pull-only, so Set Up Client omits the publish instructions on an upstream registry. Publish to a virtual registry instead, or cache packages through the upstream proxy.

Next steps

Last updated

Was this helpful?