Aptly and community search.

aptly/versions/1/README.md

@@ -0,0 +1,123 @@
+# 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.