# Aptly

Aptly is a Debian/Ubuntu APT repository management tool. Use it to mirror upstream repositories, create package snapshots, and publish private or curated APT repositories that your machines can install from.

## Configuration

Key settings in your instance's `config.yaml`:

- **domain** - Where aptly will be accessible (default: `aptly.{your-cloud-domain}`)
- **storage** - Persistent volume size for packages and mirrors (default: `50Gi` — adjust based on how many packages you plan to mirror)

## Access

After deployment:
- `https://aptly.{your-cloud-domain}` — Published repository root (for APT clients, no auth required)
- `https://aptly.{your-cloud-domain}/api` — REST API for managing repos, mirrors, and snapshots (requires credentials)

## Credentials

The API is protected by HTTP basic authentication. The username defaults to `aptly` (configurable via `apiUser` in `config.yaml`). The password is auto-generated and stored in your instance's `secrets.yaml` under `apps.aptly.apiPassword`.

To retrieve it:
```bash
wild secret get aptly apiPassword
# or directly:
grep apiPassword path/to/secrets.yaml
```

To use the API with curl:
```bash
curl -u aptly:{your-api-password} https://aptly.{your-cloud-domain}/api/version
```

The published repository at `/` does not require credentials — APT clients can install packages without authenticating.

## First-Time Setup

1. Add and deploy:
   ```bash
   wild app add aptly
   wild app deploy aptly
   ```

2. Verify the API is responding:
   ```bash
   curl -u aptly:{your-api-password} https://aptly.{your-cloud-domain}/api/version
   ```

## Common Workflows

Aptly is managed entirely through its REST API or the `aptly` CLI (run inside the pod). The REST API docs are at https://www.aptly.info/doc/api/.

### Running aptly commands inside the pod

```bash
kubectl -n aptly exec -it deploy/aptly -- bash
```

### Mirror a Debian repository

```bash
# Create a mirror (run inside the pod, or via the REST API)
aptly mirror create debian-bookworm-main http://deb.debian.org/debian bookworm main

# Download packages
aptly mirror update debian-bookworm-main

# Snapshot the mirror
aptly snapshot create bookworm-snap from mirror debian-bookworm-main

# Publish the snapshot
aptly publish snapshot bookworm-snap
```

The published repo will be available at `https://aptly.{your-cloud-domain}/debian bookworm main`.

### Create a private package repository

```bash
# Create a local repo
aptly repo create my-packages

# Add packages
aptly repo add my-packages /path/to/package.deb

# Publish
aptly publish repo my-packages
```

### Configure a machine to use the repository

```bash
# Add the repo to sources.list
echo "deb https://aptly.{your-cloud-domain}/ bookworm main" | \
  sudo tee /etc/apt/sources.list.d/my-aptly.list

# Import the signing key (generate one first if needed — see GPG section below)
curl -s https://aptly.{your-cloud-domain}/public.key | sudo apt-key add -

sudo apt update
```

## GPG Signing

Published repositories should be signed with a GPG key. On first use, generate a key inside the pod:

```bash
kubectl -n aptly exec -it deploy/aptly -- bash

# Generate a signing key (stored in /opt/aptly/gpg)
gpg --gen-key

# Export the public key for clients to import
gpg --export --armor > /opt/aptly/public/public.key
```

Then include `--distribution`, `--component`, and signing options in your `aptly publish` commands. See https://www.aptly.info/doc/aptly/publish/snapshot/ for details.

## Notes

- GPG keys and all aptly data (database, package pool, published repos) are stored on the persistent volume at `/opt/aptly`.
- The REST API (port 8080) and the nginx file server (port 80) both run inside the pod via supervisord. The ingress routes to nginx (port 80).
- `storage` defaults to `50Gi`. A full Debian mirror for a single architecture is ~50–100 GiB; plan accordingly.