Self-hosted license server: a practical guide

What a license key server does

Whatever it is called, a license key server for installed software has four jobs:

• Issue keys: by hand, in bulk, or automatically from your shop when someone pays.
• Activate a key on a device the first time it is used, and enforce how many devices a license allows.
• Validate: answer the application’s check with the license’s status, plan, expiry and features.
• Revoke: suspend, revoke or let keys expire, so the next check fails.

Most sellers also need release downloads for licensed customers, a way for customers to move a license to a new computer, and an audit trail of who changed what.

License key server or floating license manager?

Search results for “license server” mix two different kinds of software. A floating (concurrent) license manager hands out a limited pool of seats to users on a network, usually inside one company, and takes a seat back when someone closes the program. A license key server, the subject of this guide, issues individual keys to customers, binds each key to a number of devices and checks it over the internet.

Velsigil is a license key server. It does not do floating or concurrent seats, and it does not meter usage. If you need a seat pool shared on a company network, you need a different kind of tool.

Build it, rent it or run it yourself

There are three ways to get a license server, and none is right for everyone.

Build your own

You control everything and pay nothing for software. You also own every security decision: key generation, response signing, replay protection, device binding, rate limits, a customer portal and a staff panel with access control. A licensing system is built once and then defended for as long as you sell, which is usually more work than it looks at the start.

Rent a hosted licensing service

Someone else runs the server, so there is little operations work. In exchange, your customer list and license data live on another company’s systems, and you depend on that service for as long as your shipped builds call it.

Run licensing software on your own server

You get a finished system and keep the data and the address. You take on the operations: a server, TLS certificates, backups, updates and monitoring. This is the model Velsigil follows: commercial, proprietary software where each installation serves one seller, on a Linux or Windows server you control, paid as a subscription whose plan sets how many production installations you may run and which features you get (see pricing).

Whichever you choose, decide on the address first. Every build you ship calls the license server at the address it was compiled with, and a well-designed client never follows redirects. Use a host name on your own domain that you will keep for years, such as licenses.example.com, not one tied to a server or a provider.

What you need to run one

Velsigil runs as a set of Docker containers: the application (Node.js and TypeScript) and PostgreSQL 18 on an internal network, plus optional ClamAV to scan uploaded releases. Background jobs handle license expiry, webhook delivery, data retention and security checks. Its documentation sizes it like this:

ClamAV adds about 1 vCPU, 3 GB of memory and 2 GB of disk. Velsigil runs as a single instance: rate limits and detectors are kept in memory, so you scale it with a bigger server, not behind a load balancer. PostgreSQL can also be an external or managed database.

Linux with Docker Compose

The Linux setup is designed for a fresh Ubuntu 22.04 or 24.04 LTS or Debian 12 server, on x86_64 or arm64. Caddy sits in front with automatic HTTPS, HSTS and edge rate limits, and it is the only container that publishes ports. Every container drops all Linux capabilities except the few its image needs and runs with no-new-privileges. The application runs as a non-root user, and the application, migration, Caddy and database containers have read-only root file systems. Migrations run in a separate one-shot container, so the long-running application holds only a data role in the database.

bash deploy/install.sh --domain licenses.example.com --email ops@example.com

The installer installs Docker, hardens the host (firewall, fail2ban, unattended upgrades and, optionally, key-only SSH), generates the secrets on the server, starts the stack, schedules backups and prints a one-time setup link. The first account becomes the owner and must enroll an authenticator app. Caddy listens on IPv4 only; to serve IPv6 visitors, put Cloudflare in front.

Windows Server with IIS

On a Windows Server that already runs IIS, Velsigil runs in Docker (Linux containers) behind IIS 10 with URL Rewrite and Application Request Routing, with certificates from Let’s Encrypt through win-acme. The application listens only on 127.0.0.1. PowerShell scripts generate the secrets on the server (readable only by Administrators and SYSTEM), set up the IIS site with site-level settings only, and register scheduled tasks for a daily backup and a weekly restore test. On Windows Server 2022 or later, the setup script restricts the site to TLS 1.2 or later; on older versions that takes a netsh binding option, where supported, or a server-wide SCHANNEL change.

The installation package for customers is being finalized during early access; early-access members get help with installation by email.

Security requirements for a license server

A license server is an attractive target: whoever controls it can mint valid licenses. Whatever you run, check for at least these properties:

• Signing keys that never leave the server. Each Velsigil product has its own Ed25519 key pair; the application gets only the public key.
• Signed answers with replay protection. The application verifies every answer, which is bound to the request’s fresh nonce and timestamp.
• Keys stored as hashes. A keyed HMAC-SHA256 and the last five characters, never the key itself; a key is shown only once.
• Protected staff accounts. Argon2id passwords, mandatory TOTP for owners and admins, re-authentication for sensitive actions, six roles and an audit log.

Velsigil’s security requirements are based on OWASP ASVS 4.0.3 Level 2. That is a design target, not a certification, and Velsigil has not had an external penetration test yet. The license key security guide covers the application side.

When the server is down

A self-hosted server will sometimes be unreachable: during an update, a hosting outage or a network problem on the customer’s side. Plan for it:

• Signed offline leases keep applications working for as many hours as you allow per product (24 by default; 0 turns them off). The SDKs use the lease only when the server cannot be reached at all, never when it answers with a refusal. See offline license activation.
• Emergency switches, including a full lockdown, never stop devices that are already activated from validating. They stop new activations, downloads, license creation or the customer portal.
• Monitoring: GET /api/health answers {"status":"ok"} for your uptime checks.

Connecting your app and your shop

• Your application uses an SDK for C# / .NET, C++, Python or Node.js, included with Velsigil as source code, or the documented client protocol. It needs three values from the product’s Integration tab, compiled into the build: the API URL, the product ID and the product’s public key.
• Your shop creates keys through the REST API with a scoped, expiring API key (for example POST /api/panel/licenses with the product, plan and quantity; the keys appear only in that response) and reacts to events such as license.created, license.revoked or license.devices_reset through signed webhooks. The outgoing webhooks are a feature of Velsigil’s Studio plan.
• Stripe Managed Payments is the one payment integration built in. It is optional and a feature of Velsigil’s Studio plan. See subscription licensing with Stripe.
• Your customers have no accounts: they sign in to the customer portal with their license key to see status and devices, reset devices and download releases.

Running it day to day

Backups and restore tests

Each backup holds the database and the release files, encrypted with GnuPG (AES-256); plaintext never touches the disk. Backups are kept for 14 days, and an optional rclone job copies them off the server. Once a week, a restore test decrypts the newest backup into a throwaway PostgreSQL container and checks the tables. The security center warns when the newest backup is older than 26 hours or the last restore test older than 8 days.

Updates

On Linux, deploy/update.sh takes an encrypted backup first, keeps the running images as a rollback point, rebuilds, and runs the database migrations before the application starts. If a migration fails, the application is not started, and update.sh --rollback returns to the previous images.

Secrets and signing keys

The master secret, APP_SECRET, encrypts stored secrets and keys the license-key HMACs. It is generated on your server. Right after the installation, keep a copy in an offline password manager or vault, together with the backup key: without both, neither a backup nor the encrypted data in a restored database can be recovered. A product’s signing key can be rotated, but rotation invalidates every shipped build that embeds the old public key, so plan it together with a client release.