From b318dc28f447e4b1ac48da83a8d71e885f5aecd5 Mon Sep 17 00:00:00 2001 From: Nick Yeoman Date: Sat, 18 Jul 2026 08:06:43 -0700 Subject: [PATCH] added notes --- _docs/container-requests.md | 7 --- exportify_notes/README.md | 52 ++++++++++++++++ harbor_notes/README.md | 117 ++++++++++++++++++++++++++++++++++++ 3 files changed, 169 insertions(+), 7 deletions(-) create mode 100644 exportify_notes/README.md create mode 100644 harbor_notes/README.md diff --git a/_docs/container-requests.md b/_docs/container-requests.md index 6748dfc..4c5a3bc 100644 --- a/_docs/container-requests.md +++ b/_docs/container-requests.md @@ -4,10 +4,3 @@ These are containers that have been requested to add to the repo. This used to ## The List -* Glance - dashboard - -## Apps That Will Not be in the Repo - -1. [Harbor](https://goharbor.io/) — Self-hosted container image registry. Harbor's compose file is generated by its own installer from harbor.yml (~10 tightly coupled services); a static compose file in this repo would drift immediately. Use the official installer. - -2. [Exportify](https://github.com/watsonbox/exportify) — Spotify playlist CSV exporter. No published container image (Dockerfile only), and the hosted version at https://exportify.app/ runs entirely in the browser with no server-side data storage. diff --git a/exportify_notes/README.md b/exportify_notes/README.md new file mode 100644 index 0000000..acd9c1e --- /dev/null +++ b/exportify_notes/README.md @@ -0,0 +1,52 @@ +# Exportify + +Exportify exports your Spotify playlists (tracks, artists, albums, and audio features) to CSV files. It has no published container image — only a Dockerfile you'd have to build yourself — and the hosted version runs entirely client-side in the browser with no server-side data storage, so there's nothing to self-host that isn't better served by the hosted app. See `container-requests.md` for the "will not be in the repo" rationale. + +- Project Repository: https://github.com/watsonbox/exportify +- Hosted App: https://exportify.app/ + +## Tutorial: Exporting your Spotify playlists + +### Option A — use the hosted app (recommended) + +1. Go to https://exportify.app/ +2. Click **Log in with Spotify** and authorize the app (it only requests read access to your playlists — it never modifies your Spotify account) +3. Your playlists load as a list; click **Export** next to a single playlist to download its CSV, or **Export All** to download every playlist as a zip of CSVs +4. Each CSV includes: Track URI, Track Name, Artist, Album, Release Date, Duration, Popularity, and Spotify audio-feature columns (Danceability, Energy, Key, Loudness, Tempo, etc.) + +Since everything runs in your browser and talks directly to Spotify's API, no data passes through or is stored on any third-party server. + +### Option B — run it yourself (no published image, build from source) + +Only worth doing if you don't trust the hosted instance or want to self-host on an internal network. + +```bash +git clone https://github.com/watsonbox/exportify.git +cd exportify +``` + +1. Create a Spotify app at https://developer.spotify.com/dashboard to get a Client ID +2. Add your redirect URI (e.g. `http://localhost:5000/callback` or your own domain) in the Spotify app settings +3. Copy the example env and set your client id/redirect uri: + ```bash + cp .env.example .env + nano .env + ``` +4. Build and run with the project's own Dockerfile: + ```bash + docker build -t exportify . + docker run -d --name exportify -p 5000:5000 --env-file .env exportify + ``` +5. Open `http://localhost:5000` and log in with Spotify as above + +### Using the exported CSVs + +- Import into a spreadsheet to dedupe playlists, sort by audio features, or build custom smart playlists +- Feed into other tools (e.g. `pandas.read_csv`) for playlist analysis +- Re-import isn't supported by Exportify itself — CSV export is one-way; use a separate tool (e.g. `spotify-backup`, `soundiiz`) if you need CSV-to-Spotify import + +## Gotchas + +- Spotify's API rate-limits large libraries; exporting many playlists back-to-back may need retries +- Audio-feature columns depend on Spotify's Audio Features API remaining available — Spotify has deprecated/restricted parts of this API for new apps in the past, so some columns may be blank depending on your app's API access tier +- The self-hosted route requires you to register and maintain your own Spotify Developer app (Client ID + redirect URI), which the hosted version already handles for you diff --git a/harbor_notes/README.md b/harbor_notes/README.md new file mode 100644 index 0000000..f8202db --- /dev/null +++ b/harbor_notes/README.md @@ -0,0 +1,117 @@ +# Harbor + +Harbor is a self-hosted OCI container image registry with vulnerability scanning, image signing, replication, and RBAC — basically a private Docker Hub. Its compose file is generated by Harbor's own installer from `harbor.yml`, so a static `compose.yaml` in this repo would drift immediately (~10 tightly-coupled services: core, registry, database, redis, jobservice, portal, trivy, nginx, etc). Use the official installer instead of hand-rolling compose. See `container-requests.md` for the "will not be in the repo" rationale. + +- Project Repository: https://github.com/goharbor/harbor +- Documentation: https://goharbor.io/docs/ +- Releases (installer download): https://github.com/goharbor/harbor/releases + +## Tutorial: Installing Harbor + +### 1. Prerequisites + +- Docker Engine 20.10.10+ and Docker Compose 2.0.0+ on the host +- A domain name (or IP) that will be Harbor's registry hostname +- A TLS certificate, or be prepared to run without HTTPS on a trusted internal network only (Docker refuses to talk to an insecure registry over plain HTTP unless explicitly configured) + +### 2. Download the offline installer + +```bash +cd /opt +wget https://github.com/goharbor/harbor/releases/download/v2.11.1/harbor-offline-installer-v2.11.1.tgz +tar xzvf harbor-offline-installer-v2.11.1.tgz +cd harbor +``` + +Check the [releases page](https://github.com/goharbor/harbor/releases) for the current version. + +### 3. Configure `harbor.yml` + +```bash +cp harbor.yml.tmpl harbor.yml +nano harbor.yml +``` + +Key fields to set: + +```yaml +hostname: registry.example.com # the domain or IP clients will use + +http: + port: 80 + +https: + port: 443 + certificate: /your/certificate/path + private_key: /your/private/key/path + +harbor_admin_password: ChangeThisPassword + +data_volume: /data/harbor + +database: + password: ChangeThisPassword +``` + +If you don't have a certificate yet, comment out the entire `https:` block and drop `https` from downstream instructions — but note Docker clients will then need `insecure-registries` configured to push/pull (see step 6). + +### 4. Run the installer + +```bash +sudo ./install.sh +``` + +This generates `docker-compose.yml` from `harbor.yml` and brings the stack up. Optional flags: + +```bash +sudo ./install.sh --with-trivy # image vulnerability scanning +sudo ./install.sh --with-chartmuseum # Helm chart repository (deprecated upstream, skip for new installs) +``` + +### 5. Log in to the UI + +Open `https://registry.example.com` and log in as `admin` with the password set in `harbor_admin_password`. Immediately: + +1. Create a new project (e.g. `homelab`) — set it Private or Public +2. Create additional users under Administration → Users, or configure LDAP/OIDC + +### 6. Push and pull images + +```bash +docker login registry.example.com +docker tag myapp:latest registry.example.com/homelab/myapp:latest +docker push registry.example.com/homelab/myapp:latest + +# on another machine: +docker pull registry.example.com/homelab/myapp:latest +``` + +If running without TLS, add the registry to `/etc/docker/daemon.json` on every client first: + +```json +{ + "insecure-registries": ["registry.example.com:80"] +} +``` + +then `sudo systemctl restart docker`. + +### 7. Use it as a pull-through cache / replication target (optional) + +Administration → Registries lets you add Docker Hub (or another registry) as an endpoint, then Administration → Replications to mirror images in on a schedule — useful for caching frequently-pulled base images locally. + +### 8. Day-2 operations + +```bash +cd /opt/harbor +sudo docker compose down +sudo ./install.sh # re-run after editing harbor.yml to regenerate and restart +``` + +Back up `data_volume` (default `/data/harbor`) and the Postgres data inside it before any upgrade. Upgrades are major-version-specific — always read the [upgrade guide](https://goharbor.io/docs/edge/administration/upgrade/) for your version jump, don't just re-run the new installer over old data blindly. + +## Gotchas + +- Trivy's vulnerability database downloads on first scan and needs outbound internet access; air-gapped installs need `--with-trivy` plus manually seeding the DB. +- The installer's generated `docker-compose.yml` is meant to be managed by `install.sh`, not edited by hand — re-running the installer after config changes is the supported workflow. +- Harbor's own `database` and `redis` containers store state locally by default; point `harbor.yml` at external Postgres/Redis instead if you already run those services elsewhere.