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 charsNode 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
dataDirmust 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, WindowsMachineGuid, macOSIOPlatformUUID) 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_IDfirst. Operators use it in containers, see Containers and Kubernetes.