April 16, 2026
Building a license-gated catalog for a paid NAS product
How I protect 3,368 curated Docker templates behind a license check in Eight.ly Professional without breaking offline use, and what shipped versus what didn't.
The catalog is the moat. Eight.ly Professional ships access to 3,368 self-hosted Docker apps organized into 14 groups with around 60 subcategories. The templates themselves are not the moat, because anyone can write a Sonarr compose file. The curation is the moat. The taxonomy is the moat. The stream of updates is the moat. If a single customer can extract the whole catalog and drop it into a forked competitor, every future sale is a sale to someone who could have used the fork for free.

So the catalog had to move behind a license check. The constraint was that it could not break offline use, because the people I am selling to run NAS boxes that sometimes sit in a closet with flaky internet, and they will not forgive a product that goes dark when the WAN does.
What the license check actually buys
The design has four layers, and only the first one shipped. License-gated updates mean a pirate's catalog rots within weeks. Signed manifests mean the client refuses tampered catalogs, so a pirate has to ship a patched binary, not just files. Per-license watermarking means every catalog copy carries traceable fingerprints, so a leak becomes attributable. Revocation means a leaked license stops receiving updates.
None of that requires the client to phone home on every deploy. All the network activity happens during a sync pass, which runs on a 24-hour ticker or when the user clicks "Sync now." A customer working offline for a week does not notice. A pirate working offline forever gets a stale catalog. That tradeoff is the whole point.
The client lives in pkg/api/license/
Professional Edition gets a Go package at pkg/api/license/. State is a single persisted blob: license key, an install_id generated on first boot, the activation token, edition, heartbeat times, and the catalog version. The activation token is the bearer credential for the upstream API and never leaves the box in the status payload the frontend reads.
// pkg/api/license/license.go (e1605d27)
type State struct {
LicenseKey string `json:"license_key"`
InstallID string `json:"install_id"`
ActivationToken string `json:"activation_token"`
Edition string `json:"edition"`
ValidUntil string `json:"valid_until,omitempty"` // ISO8601, empty = perpetual
ActivatedAt time.Time `json:"activated_at"`
LastHeartbeat time.Time `json:"last_heartbeat"`
LastManifestCheck time.Time `json:"last_manifest_check,omitempty"`
CatalogVersion string `json:"catalog_version,omitempty"`
}
The install_id is a UUID minted once on first boot. Activation sends {license_key, install_id} to the update server and stores whatever activation token comes back:
// Activate binds this install to the given license key. On success,
// persists the activation token to disk. (e1605d27)
func (c *Client) Activate(licenseKey string) error {
licenseKey = strings.ToUpper(strings.TrimSpace(licenseKey))
if licenseKey == "" {
return fmt.Errorf("license key required")
}
c.mu.Lock()
installID := c.state.InstallID
if installID == "" {
installID = uuid.New().String()
c.state.InstallID = installID
}
c.mu.Unlock()
body, _ := json.Marshal(map[string]string{
"license_key": licenseKey,
"install_id": installID,
})
// ... POST /v1/license/activate, then on success store out.ActivationToken
}
The status the web UI sees never includes the activation token, and the key itself is masked down to ZSXYBT-XXXXXX-XXXXXX-8R8BHF so an over-the-shoulder reader cannot copy it but the owner can still recognize it.
The sync pass is one boring loop
The interesting part is CatalogService, a goroutine on a 24-hour ticker. Every pass does the same thing: fetch the manifest, compare each template's sha256 against what is already on disk, download only what changed, and atomic-swap it into place.
// pkg/api/license/catalog_service.go (e1605d27)
for _, t := range m.Templates {
appDir := filepath.Join(cs.root, t.Group, t.Subcategory, t.Name)
if fresh, _ := cs.localMatches(appDir, t.Sha256); fresh {
skipped++
continue
}
if err := cs.fetchAndApply(t, appDir); err != nil {
log.Printf("[catalog-sync] %s: %v", t.ID, err)
errors++
continue
}
downloaded++
}
localMatches recomputes the same digest the server emits: sorted filenames, then each name and its contents written into one sha256 with null separators. It is deterministic across rebuilds, which is what lets the client tell "this template actually changed" apart from "this was just rebuilt." A whole pass over 3,368 entries where nothing changed is mostly disk reads.
The apply step extracts to a sibling tmp dir and renames into place, so a crash mid-write never leaves a half-written app directory:
// extract to <appDir>.tmp-<timestamp>, then rename — crash safety
// without fsync-per-file. (e1605d27)
tmp := appDir + ".tmp-" + time.Now().Format("20060102150405")
// ... gunzip, walk the tar, reject any path that isn't a bare filename ...
if filepath.Base(hdr.Name) != hdr.Name || hdr.Name == "" {
return fmt.Errorf("refusing suspicious tarball path: %q", hdr.Name)
}
A syncMu serializes the whole Sync() call, so a manual "Sync now" click landing in the middle of a scheduled tick does not put two passes into the same tmp directory fighting over the same files. That was a real race I had to close before I trusted the button.
The server side, honestly
The other end of all this is updates.eight.ly, a small service that mints keys, binds activations, and serves the manifest and tarballs. It lives outside this repo, so I am not going to embed code I cannot show you the commit for. What I can say is that the client contract is the part I trust, because it is the part where my product runs my code on a customer's box. The key format the client validates is four groups of six characters; the entropy, the check digit, and the pepper that backs them live server-side, and I am describing them, not proving them here.
The catalog-sync feed into that server is a cron on the host pulling the private templates repo with a deploy key, not a GitHub Actions workflow. The Actions version stalls because private-repo runners on this org's plan do not get assigned, which is a billing problem, not a code problem, and it is tracked separately. The cron is the workaround and it has been steady since I installed it.
Four phases, one shipped
The spec has four phases: license MVP, Ed25519 signing, per-license watermarking, and a revocation admin UI. Phase 1 is live. Phases 2 through 4 are not, on purpose. Signing is worth building when you have pirates, pirates require customers, and customers require a shipped product. I would rather ship with unsigned catalogs now and add signing before there is a leak worth watermarking than block the launch on a threat that does not exist yet.
The debt I am taking on is explicit. An air-gapped enterprise customer cannot get signed bundles yet. A takedown does not have attribution data yet. A revoked license keeps working locally until it checks back in. All of that is fine at launch. None of it is fine at a hundred customers, which is exactly when Phase 2 is slated to start: when Professional has revenue, not when the spec was written.