Clavem

Selling and licensing self-hosted software with Stripe

Self-hosted software runs on the buyer's server, so the unit to license is an install, not a person. Give each install a stable fingerprint so a restarted container keeps its seat, check at startup and daily, and never let a failed license check take a production system down.

A seat is an install

A desktop license counts people’s computers. A self-hosted product runs on a server that many people use, so you count installs: one for production, one for staging, maybe one for a disaster-recovery copy. A device limit of 2 or 3 covers those. Name each install with an instance_name the admin recognizes, for example acme-prod or the server’s domain, because that is what they will see on the device page.

You can price the same way: per instance per year, or in tiers by size. Companies will want an invoice, so see software for businesses, and sell a higher device limit to buyers with several environments.

Containers lose their state

Self-hosted software often runs in Docker or on an orchestrator, where a container is replaced at each deploy. If the instance id from activation lives in the container’s file system, every redeploy activates again and uses another seat, until the license limit blocks a deploy at 2 a.m.

Two defenses, which work together:

  1. Persist the license state in a volume. Store the key, the instance.id and the token in the data volume, not the image layer.
  2. Send a stable fingerprint. The License API says activating again with a fingerprint already active on the license returns that seat, with its name updated. If the fingerprint is the same after every rebuild, the volume can even be lost without cost. A good source is a hash of the configured base URL or a random install id kept in the volume. Do not hash the container id or the hostname of an ephemeral pod, which change on every start.

A compose file that supports this:

services:
  app:
    image: example/app:3.2
    environment:
      LICENSE_KEY: ${LICENSE_KEY}
      INSTANCE_NAME: acme-prod
    volumes:
      - app-data:/var/lib/app   # holds license.json with the instance id and token
volumes:
  app-data:

Read the key from an environment variable or a secrets mount, not from the image.

Check at startup and on a schedule

A server does not have a “launch” a human triggers. Use two moments:

  • At startup: validate with the stored instance_id, with a short timeout. On a valid answer, store the new token. If the call fails, verify the stored token locally and carry on.
  • Once a day: a scheduled job validates again. Each success restarts the 14-day window of the token.

A single validation per day per install is nowhere near the limit of 60 requests a minute per license key, but many installs sharing one key, such as a site license, can add up at restarts. Add random delay to scheduled checks so that a fleet restarting together does not call at the same second.

Never take production down

A license check that stops the application when it fails will, one day, stop it for a paying customer: a DNS problem, a firewall change, a certificate expiry on their side. Decide what the product does in each state, and write it into the documentation:

State Behavior
Valid Everything works
Cannot reach Clavem, token fresh Everything works; no warning
Cannot reach Clavem, past refresh_by Keep working; show an admin banner with the date it last checked
Past refresh_by for more than a stated period (for example 30 days) Restrict optional features or new seats; never data access
valid: false (expired or disabled) Show the reason from error; restrict features as the contract says; keep data readable and exportable

Your customers’ data is theirs. Whatever you restrict, never block reading or exporting it.

Air-gapped and locked-down sites

Some buyers run servers with no outbound internet. Clavem’s token lets the install verify its license with a public key in your code, and the token is not bound to a device. An admin can validate from a connected machine, copy the token across, and the install trusts it until refresh_by. For longer gaps, extend the grace period for those customers in your product, or sell them a license with a long fixed validity. See offline verification and the offline-first article.

Delivering the software

Clavem hosts release files for gated download: each can be up to 5 GiB, and a valid key gets a signed link that lasts an hour. That suits binaries, tarballs, installers and docker save archives. It is not a container registry: Clavem cannot answer docker pull. If you distribute images through a private registry, keep that, and use Clavem for the keys, the downloads of non-image artifacts and the update check. See releases and downloads.

Setting Suggested value Why
License type Annual subscription per install, or perpetual with a paid support term Hosting costs recur for the buyer; support and updates recur for you
Device limit 2 or 3 Production, staging and a spare
Trial 14 to 30 days, or a feature-limited community edition Admins install before they buy
Updates Releases endpoint with the key in X-License-Key Gate new versions on a current license

Doing this with Clavem

Create a product, connect Stripe, map the price, and set the device limit per tier by mapping each Stripe price to the right product. A buyer gets a key and an order page with the download. The install activates at first start and validates daily. Pick your server language’s guide: Go, Node.js, PHP, Python or Java.

Guides to follow

Questions

What should happen when a self-hosted app cannot reach the license server?

Keep running. Trust the last signed token until its refresh date, then show a warning in the admin area, and restrict only new or optional features if the lapse continues. Stopping a production service over a failed check turns a licensing question into an outage.

How do I stop a container restart from using another license seat?

Send a stable fingerprint when you activate. Activating again with a fingerprint already active on the license returns the same seat instead of creating a new one. Derive it from something that survives restarts, such as the configured domain.