Skip to Content
PortcullisDocs
Integrate (product engineers)

Fingerprint

Compute a stable, product-salted installation fingerprint.

The fingerprint identifies one installation (machine). It must stay the same across restarts and upgrades. It is 64 hex characters.

Algorithm

installationId = env PORTCULLIS_INSTALLATION_ID
              ?? read <dataDir>/installation-id
              ?? (create random UUID, write <dataDir>/installation-id)
fingerprint    = hex( sha256( "portcullis:" + productCode + ":" + installationId ) )   // 64 hex chars

Node example

import { createHash, randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';

export function getInstallationId(dataDir: string): string {
  const fromEnv = process.env.PORTCULLIS_INSTALLATION_ID?.trim();
  if (fromEnv) return fromEnv;

  const file = join(dataDir, 'installation-id');
  if (existsSync(file)) return readFileSync(file, 'utf8').trim();

  const id = randomUUID();
  mkdirSync(dataDir, { recursive: true });
  writeFileSync(file, id);
  return id;
}

export function computeFingerprint(productCode: string, installationId: string): string {
  return createHash('sha256')
    .update(`portcullis:${productCode}:${installationId}`)
    .digest('hex');
}

Rules

  • dataDir must be a persistent volume (Docker volume, Kubernetes persistent volume claim). Document this in your product's install guide. If it is lost, the installation looks like a new machine and uses another seat.
  • Never send the raw installation ID; only the fingerprint.
  • Using the OS machine ID instead (/etc/machine-id, Windows MachineGuid, macOS IOPlatformUUID) is allowed. It binds more strongly on bare metal but is fragile in containers. Your product team decides; the formula stays the same.
  • Always honour PORTCULLIS_INSTALLATION_ID first. Operators use it in containers, see Containers and Kubernetes.

On this page