> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/alpine-apk.md).

# Alpine

Alpine - host Alpine packages in Harness Artifacts

Use an **Alpine** registry to host private Alpine Linux packages and serve them to Alpine Package Keeper (apk).

## What you will learn from this topic

By the end of this guide, you will know how to:

* 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 an Alpine Registry

To create an Alpine Registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**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.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Alpine** as the **Registry type**.
7. Click **Save**
8. Select **Create** to finalize.

{% hint style="info" %}
**RSA Signing Key**

Self-published indexes are unsigned, so apk commands against this registry require the `--allow-untrusted` flag unless you configure a signing key. Optionally, 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](https://developer.harness.io/artifact-registry/3.0/security-and-compliance/signing-keys/setup-signing.md).
{% endhint %}

## Upstream proxy configuration (optional)

An upstream proxy allows your registry to fetch Alpine packages from an external source when they are not available locally. The default upstream is the Alpine Linux package mirror.

### Create upstream proxy

To create an upstream proxy:

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 **Alpine** as the **Registry type**.
7. Select the **Source**: **Alpine Linux** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL**.
8. Select the **Authentication method**.
   * **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. This works for the public Alpine Linux mirror.
9. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing Alpine 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.

{% hint style="info" %}
**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.
{% endhint %}

## Alpine client setup

In your Harness Alpine Artifact, select **Setup 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 Alpine Artifact, select **Setup 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>`.

{% hint style="info" %}
**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.
{% endhint %}

### 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`:

```bash
sudo sh -c "echo 'https://<EMAIL>:<IDENTITY_TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/alpine/<BRANCH>/<REPOSITORY>' >> /etc/apk/repositories"
```

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

Refresh the index:

```bash
apk update --allow-untrusted
```

**2. Publish a package**

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

```bash
curl --request PUT 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/alpine/<BRANCH>/<REPOSITORY>/<ARTIFACT_NAME>-<VERSION>.apk' \
  --header 'x-api-key: <IDENTITY_TOKEN>' \
  --data-binary '@<PACKAGE_FILE>'
```

**3. Install a package**

Install the package with `apk`:

```bash
apk add --allow-untrusted <ARTIFACT_NAME>=<VERSION>
```

## Setup verification

Confirm that your registry serves the package you published. To verify your setup:

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 **Setup 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](#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 shows the shape of a publish step. Replace `<PUBLISH_COMMAND>` with the publish command from the earlier steps. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        <PUBLISH_COMMAND> --version "$PACKAGE_VERSION"
```

## Troubleshooting

<details>

<summary>`apk update --allow-untrusted` fails with `401` or `403`</summary>

Check that the username and identity token in your `/etc/apk/repositories` entry match the registry address and token shown in **Setup 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.

</details>

<details>

<summary>`apk add` fails with an untrusted signature error</summary>

Self-published indexes in Artifact Registry 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](https://developer.harness.io/artifact-registry/3.0/security-and-compliance/signing-keys/setup-signing.md).

</details>

<details>

<summary>A publish with `curl --request PUT` returns `409 Conflict`</summary>

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.

</details>

<details>

<summary>`apk add` cannot find the package or reports unsatisfiable constraints</summary>

Check that `<ARTIFACT_NAME>` and `<VERSION>` match the values from the `.PKGINFO` of the package you published, and that `<BRANCH>` and `<REPOSITORY>` in your repository URL match the path you published to.

</details>

<details>

<summary>Setup Client does not show a publish step</summary>

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

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
