Self-Hosted Software Licensing: A Practical Guide
Use Docker Engine with Compose v2 to run the self-hosted LicenseFerry API, admin console, and a private PostgreSQL 17 database. Start with the release source package from your account.
Start the API and database with Docker Compose
From the extracted release directory, create the deployment environment, build the API image, and start the stack. Use distinct secrets for staging and production.
./deploy/self-hosted/init-env.sh
docker compose --env-file deploy/self-hosted/.env -f deploy/self-hosted/compose.yaml build api
docker compose --env-file deploy/self-hosted/.env -f deploy/self-hosted/compose.yaml up -d --wait --no-build
curl --fail http://127.0.0.1:3681/healthRun the organization provisioning steps in the package’s docs/deployment/self-hosted.md guide and unlock the console with your admin token. Publish the API behind a TLS reverse proxy and keep PostgreSQL private.
Back up and verify recovery
Keep encrypted database backups and protect the original license master key separately. A database restore needs that key to match existing licenses. Restore into an isolated instance and use a test license to check status and device counts. Verify the result before trusting your backup schedule.
Upgrade and roll back
Pin the server release. Before applying a schema migration, back up the database and verify the new server on an isolated copy. Document which server version can run with each schema version. A downgrade can require restoring the pre-upgrade backup.
Move a server without changing every client
If you control the hostname and client protocol, stage a replacement server and test TLS, DNS caching, and validation from supported app versions before updating your endpoint. Document any required app release for older clients. Check the client API and compare deployment responsibilities.