Installation¶

For this example installation I am using an Ubuntu 22.04 LTS server, accessed over SSH with PuTTY. Any Linux host with Docker (or Podman) will work.

1. Access your server¶

Connect to your machine through your own means and move to the working folder where you want LicenseTrack to live. In this example that is the user's home directory.

Logged in to the server, sitting in the home folder

2. Download the latest release¶

Grab the latest release from GitHub. Here I use wget:

wget https://github.com/zndr88/LicenseTrack/archive/refs/tags/v1.1.22.zip

Always use the current latest version

The commands here use v1.1.22. Check the latest release and substitute its version tag throughout. Some screenshots on this page were captured on an earlier version — the look and feel is unchanged, only the version number differs.

Downloading the release archive with wget

3. Unzip and enter the folder¶

unzip v1.1.22.zip
cd LicenseTrack-1.1.22

Unzipping the archive and changing into the folder

4. Create your environment file¶

Create your own .env from the provided example:

cp .env.example .env

Generate a JWT secret:

Linux / macOSWindows PowerShell

openssl rand -hex 32

-join ((0..31) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })

Copy that value somewhere safe, then open the .env file in the editor of your choice (I prefer vi) and paste it in as your JWT_SECRET.

Setting JWT_SECRET in the .env file

Change any other setting you like — for this example we keep the defaults. Scroll down to ADMIN_PASSWORD and set a non-standard first-time password. You will be required to change it on first login.

Startup rejects weak values

The app refuses to start if JWT_SECRET is missing or unsafe, or if ADMIN_PASSWORD is blank or a common default such as admin, password, or changeme. Pick a real password here.

Setting ADMIN_PASSWORD in the .env file

Save and exit the file.

Keep your .env private

Your .env holds your JWT secret and admin password. Never commit it to source control or share it.

5. Launch¶

We are ready to launch. This example uses Docker (Podman works too):

docker compose up -d --build

Running docker compose up

Wait for it to finish — it downloads the dependencies and builds the image, so the first run takes a few minutes.

Build completed

6. Verify¶

Once the stack is up, confirm the API is healthy:

curl http://localhost:8080/api/health

You should get back:

{"status":"ok"}

Health check returning status ok

Once verified, you can log off the server. The next steps happen from your local machine.

Deploying for real?

This walkthrough gets you a working instance with default settings. Before exposing LicenseTrack beyond your own machine — HTTPS, reverse proxy, CORS, the full configuration reference — read Production deployment & hardening.

First launch & login