Let an installation look different via ENVIRONMENT_NAME and ENVIRONMENT_COLOR

Setting ENVIRONMENT_NAME (and optionally ENVIRONMENT_COLOR, a name or hex
value) gives the sidebar that colour, adds a name badge next to the title and
on the sign-in page, and prefixes the browser tab title, so a dev copy can't
be taken for production. Unset, nothing changes. The colour is validated to a
plain #rrggbb before it reaches the page's styles. A public
GET /api/environment lets the sign-in page use it too.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-13 20:59:25 +02:00
1 parent 44cc9d1cf2
commit 7e196be56d
11 files changed
+253 -3

No files matched your search

+4
View File
@@ -74,6 +74,10 @@ export function createApp() {
app.get("/health", (_req, res) => res.json({ ok: true }));
// What this installation calls itself and how it should look (a dev copy in a different colour), asked for before sign-in so the
// login page can show it too. Just a label and a colour.
app.get("/api/environment", (_req, res) => res.json({ environment: env.environment }));
// Publicly readable so `curl .../agent/linux/install.sh | bash` works from a
// freshly provisioned server with no prior session. Contains no secrets.
if (existsSync(agentDir)) {
+47
View File
@@ -1,3 +1,48 @@
/** Colours that can be asked for by name; all dark enough to carry white text. Anything else must be a hex colour. */
export const ENVIRONMENT_COLORS: Record<string, string> = {
red: "#b91c1c",
orange: "#c2410c",
amber: "#b45309",
green: "#15803d",
teal: "#0f766e",
blue: "#1d4ed8",
purple: "#7e22ce",
pink: "#be185d",
gray: "#475569",
grey: "#475569",
};
const DEFAULT_ENVIRONMENT_COLOR = ENVIRONMENT_COLORS.orange;
export interface EnvironmentLook {
/** Shown as a badge and in the browser tab; may be empty when only a colour was set. */
name: string;
/** A #rrggbb colour. */
color: string;
}
/**
* How this installation says what it is — so a dev copy can't be mistaken for production. Both values come from the environment
* (ENVIRONMENT_NAME, ENVIRONMENT_COLOR). Neither set means a normal look; a name alone gets a default colour. The colour is only
* ever a validated #rrggbb value, because it is placed into the page's styles.
*/
export function parseEnvironment(nameRaw: string | undefined, colorRaw: string | undefined): { look: EnvironmentLook | null; warning?: string } {
const name = (nameRaw ?? "").replace(/\p{Cc}/gu, "").trim().slice(0, 24);
const wanted = (colorRaw ?? "").trim().toLowerCase();
let color: string | null = null;
let warning: string | undefined;
if (wanted) {
if (ENVIRONMENT_COLORS[wanted]) color = ENVIRONMENT_COLORS[wanted];
else if (/^#[0-9a-f]{6}$/.test(wanted)) color = wanted;
else if (/^#[0-9a-f]{3}$/.test(wanted)) color = `#${wanted[1]}${wanted[1]}${wanted[2]}${wanted[2]}${wanted[3]}${wanted[3]}`;
else warning = `ENVIRONMENT_COLOR "${colorRaw}" isn't a colour name (${Object.keys(ENVIRONMENT_COLORS).join(", ")}) or a hex value like #b45309 — using the default.`;
}
if (!name && !color) return { look: null, warning };
return { look: { name, color: color ?? DEFAULT_ENVIRONMENT_COLOR }, warning };
}
const environmentLook = parseEnvironment(process.env.ENVIRONMENT_NAME, process.env.ENVIRONMENT_COLOR);
export const env = {
port: Number(process.env.PORT ?? 3000),
nodeEnv: process.env.NODE_ENV ?? "development",
@@ -11,6 +56,8 @@ export const env = {
clientId: process.env.AUTHENTIK_CLIENT_ID ?? "",
clientSecret: process.env.AUTHENTIK_CLIENT_SECRET ?? "",
},
environment: environmentLook.look,
environmentWarning: environmentLook.warning,
get authEnabled() {
return Boolean(this.authentik.issuerUrl && this.authentik.clientId && this.authentik.clientSecret);
},
+2
View File
@@ -25,6 +25,8 @@ import { initKumaMaintenanceScheduler } from "./services/kumaMaintenanceSchedule
}
warnIfAuthNotConfigured();
if (env.environmentWarning) console.warn(env.environmentWarning);
if (env.environment) console.log(`Environment: ${env.environment.name || "(unnamed)"} (${env.environment.color})`);
await runMigrations();
{
const converted = await encryptStoredSettingsSecrets();
+85
View File
@@ -0,0 +1,85 @@
/**
* Making a dev installation look different from production (ENVIRONMENT_NAME / ENVIRONMENT_COLOR).
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
const dir = mkdtempSync(join(tmpdir(), "hm-environment-"));
process.env.DATABASE_PATH = join(dir, "test.sqlite");
process.env.SESSION_DIR = join(dir, "sessions");
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
process.env.ENVIRONMENT_NAME = "Dev";
process.env.ENVIRONMENT_COLOR = "teal";
const { parseEnvironment } = await import("../src/env.js");
const { createApp } = await import("../src/app.js");
describe("parseEnvironment", () => {
test("nothing set is a normal installation", () => {
assert.deepEqual(parseEnvironment(undefined, undefined), { look: null, warning: undefined });
assert.deepEqual(parseEnvironment(" ", ""), { look: null, warning: undefined });
});
test("a name alone gets the default colour", () => {
const { look } = parseEnvironment("Dev", undefined);
assert.equal(look?.name, "Dev");
assert.match(look?.color ?? "", /^#[0-9a-f]{6}$/);
});
test("colours by name or as hex, in any case, short hex expanded", () => {
assert.equal(parseEnvironment("x", "Blue").look?.color, "#1d4ed8");
assert.equal(parseEnvironment("x", "#B45309").look?.color, "#b45309");
assert.equal(parseEnvironment("x", "#0af").look?.color, "#00aaff");
});
test("a colour alone is accepted, with no name", () => {
assert.deepEqual(parseEnvironment(undefined, "green").look, { name: "", color: "#15803d" });
});
test("anything that is not a plain colour is refused, never passed on into the page's styles", () => {
for (const bad of ["red; background:url(//evil)", "url(x)", "#12345", "rgb(1,2,3)", "</style><script>", "#zzzzzz"]) {
const { look, warning } = parseEnvironment("Dev", bad);
assert.match(look?.color ?? "", /^#[0-9a-f]{6}$/, `${bad} falls back to a safe colour`);
assert.ok(warning, `${bad} is reported`);
}
});
test("the name is cleaned of control characters and capped in length", () => {
assert.equal(parseEnvironment("De\u0000v\n", undefined).look?.name, "Dev");
assert.equal(parseEnvironment("x".repeat(100), undefined).look?.name.length, 24);
});
});
describe("GET /api/environment", () => {
let server: Server;
let base = "";
before(async () => {
server = await new Promise<Server>((resolve) => {
const s = createApp().listen(0, "127.0.0.1", () => resolve(s));
});
base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
});
after(() => {
server.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("is answered without signing in, so the login page can look the part too", async () => {
const res = await fetch(`${base}/api/environment`);
assert.equal(res.status, 200);
assert.deepEqual(await res.json(), { environment: { name: "Dev", color: "#0f766e" } });
});
});