> 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/debian-apt.md).

# Debian

Debian - host Debian packages in Harness Artifacts

Use a **Debian / APT** registry to host, proxy, and distribute `.deb` packages for Debian and Ubuntu systems using APT.

## 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 the APT package manager on your local machine. APT is available by default on Debian and Ubuntu systems.
* Install `curl`. You use it to publish `.deb` files and Debian source files to your registry.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Debian registry

To create a Debian / APT 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*.

{% hint style="info" %}
**Private Debian registry**

A private Debian / APT registry in Harness Artifacts hosts and distributes packages only to authenticated clients.
{% endhint %}

6. Select **Debian** as the **Registry type**.
7. Optionally, in the **Debian Configuration** section, set the **Indexed Remote Architectures** and **Index Compression Formats**.

{% hint style="info" %}
**Indexed remote architectures**

Indexed Remote Architectures lists the architectures Harness indexes from remote repositories on this registry. The defaults are `amd64`, `i386`, and `arm64`. Select from these defaults, or enter a custom architecture name to index additional architectures from remote repositories. If you leave the field empty, Harness indexes every available architecture, which increases cold-start index generation time and cost.
{% endhint %}

{% hint style="info" %}
**Index compression formats**

Harness generates a `.gz` index for your registry by default. Optionally, select **XZ** (`.xz` extension) in Index Compression Formats for a smaller index; doing so increases cold-start index generation time and cost.
{% endhint %}

8. Select **Save**.
9. Select **Create** to finalize.

{% hint style="info" %}
**GPG signing key**

Optionally, attach a GPG signing key to your registry so Harness signs repository metadata and clients can verify packages with `apt update`. To create or import a key and configure your registry and clients, go to [Set up signing keys](https://developer.harness.io/artifact-registry/3.0/security-and-compliance/signing-keys/setup-signing.md) to configure package signing.
{% endhint %}

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Debian packages from external repositories, such as official Debian or Ubuntu mirrors, when they are not available locally.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry**, then 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 **Debian** as the **Registry type**.
7. Select **Custom** as the **Source**, then specify the **Remote registry URL** (for example, `http://deb.debian.org/debian`).

{% hint style="info" %}
**Remote registry URL format**

The remote registry URL must point to the parent directory of the `dists` folder for that repository. For example, `http://deb.debian.org/debian` is correct, because `http://deb.debian.org/debian/dists/` contains the release metadata. If you use another Debian mirror or a private repository, confirm the URL ends at that parent level, not at a distribution or component subdirectory.
{% endhint %}

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 public Debian repositories.
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 Debian / APT Artifact.
2. Navigate 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 repository and caches it locally. Subsequent installs for the same package version are served from the cache.
{% endhint %}

{% hint style="info" %}
**Debian metadata regeneration**

Harness regenerates Debian registry metadata when you upload or delete a package, or when you add or remove an upstream proxy from a registry. This operation can take a few minutes, so your changes might not appear in APT metadata immediately.
{% endhint %}

## Debian / APT client setup

In your Debian / APT Artifact, select **Setup Client**. The dialog gives you an identity token, then instructions to configure APT, publish packages, and install packages.

### Generate an identity token

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

1. In your Debian / APT 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

In the code samples, replace the values in angle brackets with your own values.

**1. Configure APT**

Add the Debian repository to your APT sources. The `[trusted=yes]` option bypasses GPG signature verification for this repository. If you attached a signing key to your registry, go to [Set up signing keys](https://developer.harness.io/artifact-registry/3.0/security-and-compliance/signing-keys/setup-signing.md) to configure a signed repository entry instead, and omit `[trusted=yes]`.

```bash
echo "deb [trusted=yes] https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/debian <DISTRIBUTION> <COMPONENT>" | sudo tee /etc/apt/sources.list.d/harness.list
```

Create or edit the auth config file:

```bash
sudo vi /etc/apt/auth.conf.d/harness-<REGISTRY_NAME>.conf
```

Add the following content. Use your Harness account email address as `<USERNAME>`.

```
machine pkg.harness.io
login <USERNAME>
password <IDENTITY_TOKEN>
```

Update the APT cache:

```bash
sudo apt-get update
```

**2. Publish the package**

Upload a `.deb` file to the registry:

```bash
curl --location --request PUT 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/debian/deb?distribution=<DISTRIBUTION>&component=<COMPONENT>' \
--form 'file=@"<FILE_PATH>"' \
--header 'x-api-key: <IDENTITY_TOKEN>'
```

Optionally, upload the Debian source files for the package. Upload a `.dsc` file:

```bash
curl --location --request PUT 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/debian/dsc?distribution=<DISTRIBUTION>&component=<COMPONENT>' \
--form 'file=@"<FILE_PATH>"' \
--header 'x-api-key: <IDENTITY_TOKEN>'
```

Upload the source tarball. For an upstream source tarball, specify the upstream version:

```bash
curl --location --request PUT 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/debian/src?distribution=<DISTRIBUTION>&component=<COMPONENT>&package=<ARTIFACT_NAME>&version=<VERSION>' \
--form 'file=@"<FILE_PATH>"' \
--header 'x-api-key: <IDENTITY_TOKEN>'
```

**3. Use the package**

Install a package with APT:

```bash
sudo apt-get install <ARTIFACT_NAME>=<VERSION>
```

## Setup verification

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

1. On a system with no cached APT package lists for this repository, run `sudo apt-get update`, then install the package you published.
2. Confirm that APT 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. 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: |
        curl --location --request PUT "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/debian/deb?distribution=<DISTRIBUTION>&component=<COMPONENT>" \
          --form "file=@\"<ARTIFACT_NAME>_${PACKAGE_VERSION}_<ARCHITECTURE>.deb\"" \
          --header "x-api-key: <IDENTITY_TOKEN>"
```

## Troubleshooting

<details>

<summary>`apt-get update` fails with `401 Unauthorized` or `403 Forbidden`</summary>

Check that `/etc/apt/auth.conf.d/harness-<REGISTRY_NAME>.conf` contains the correct `machine`, `login`, and `password` values, and that the identity token has not expired or been revoked. Generate a new token in **Setup Client**, then update the auth config file.

</details>

<details>

<summary>A `.deb` upload returns `409 Conflict`</summary>

Debian package versions are immutable after publish. Increment the version in the package's control file, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`apt-get install` cannot find the package, or installs an old version</summary>

Run `sudo apt-get update` to refresh the local package index, and check that the package name, version, distribution, and component match the values you used to publish the package. Harness can take a few minutes to regenerate registry metadata after a publish.

</details>

<details>

<summary>Setup Client omits upload instructions for an upstream proxy registry</summary>

An upstream proxy registry only caches packages from the remote repository, so it does not accept direct uploads, and **Setup Client** does not show upload steps. Publish new packages to a standalone Debian / APT registry instead, or let clients pull them through the upstream proxy.

</details>

<details>

<summary>`apt-get install` fails signature verification</summary>

If you attached a GPG signing key to your registry, confirm the public key is imported on the client and has not expired before you retry the install.

</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 %}
