Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Separate Compose selectors from runtime authentication setup

pulse-triage[bot]fdb4018f29c5
diff --git a/.env.example b/.env.example
index 58704db643..57e4acf317 100644
--- a/.env.example
+++ b/.env.example
@@ -1,18 +1,39 @@
# Pulse Deployment Environment Variables
-# Copy this file next to your docker-compose.yml or into /etc/pulse/.env.
-# Values defined here override the UI configuration. Keep the file out of
-# version control and restrict permissions (chmod 600) because it can contain
-# credentials.
+# Reference only: every setting below is commented out. An unchanged copy
+# configures nothing. Never overwrite an existing authentication file.
+# Keep any edited deployment file private, outside version control, with
+# owner-only permissions (chmod 600). Do not source it in a shell or share it.
# -----------------------------------------------------------------------------
-# Authentication (recommended for Docker or headless installs)
+# Compose interpolation (the bundled docker-compose.yml)
# -----------------------------------------------------------------------------
-# Uncomment and set these to skip the first-run setup wizard.
-# Plain-text values are automatically hashed on startup, or supply a bcrypt hash.
-# PULSE_AUTH_USER=admin
-# PULSE_AUTH_PASS=super-secret-password
-# API_TOKENS=host-token-1,host-token-2
-# API_TOKEN=legacy-fallback-token
+# A .env beside docker-compose.yml supplies interpolation, not the container's
+# environment. The bundled file consumes only PULSE_IMAGE, PULSE_PORT and TZ;
+# placing other settings here does not pass them to Pulse.
+# PULSE_IMAGE=rcourtman/pulse:vX.Y.Z
+# PULSE_PORT=7655
+# TZ=UTC
+# Select an exact published image for your edition; see docs/DOCKER.md.
+
+# -----------------------------------------------------------------------------
+# Pulse runtime settings (not automatically forwarded by Compose)
+# -----------------------------------------------------------------------------
+# Pulse reads .env in its data directory: /etc/pulse for a default systemd
+# install, /data inside a container, or the selected PULSE_DATA_DIR.
+# Deployment-supplied environment values take precedence. Keep existing
+# credentials, encryption keys and persistent data intact; do not replace an
+# installation's .env with this example. See docs/CONFIGURATION.md.
+
+# Authentication
+# For a new install, leave PULSE_AUTH_USER and PULSE_AUTH_PASS unset and use
+# browser bootstrap setup: docs/INSTALL.md#step-1-get-the-token.
+# Headless automation: docs/CONFIGURATION.md#private-docker-authentication-file
+# shows a private credential file for docker run, not a Compose interpolation
+# recipe. Use a complete bcrypt hash; startup hashing does not remove a
+# plaintext password from Docker's environment or your deployment file.
+# API_TOKEN and API_TOKENS are ignored in v6. Create scoped tokens in
+# Settings > API Access; see SECURITY.md#api-token-authentication.
+# Never put a password or token in command arguments, a URL or a public report.
# -----------------------------------------------------------------------------
# Optional security toggles
@@ -34,8 +55,3 @@
# CONNECTION_TIMEOUT=10
# LOG_LEVEL=info
# METRICS_RETENTION_DAYS=7
-
-# -----------------------------------------------------------------------------
-# Miscellaneous
-# -----------------------------------------------------------------------------
-# TZ=UTC
diff --git a/scripts/tests/test_configuration_auth_docs.py b/scripts/tests/test_configuration_auth_docs.py
index 53f3a805d6..ba5d2e0f17 100644
--- a/scripts/tests/test_configuration_auth_docs.py
+++ b/scripts/tests/test_configuration_auth_docs.py
@@ -86,6 +86,50 @@ def private_file(home: Path, content: str = CONTENT) -> Path:
class ConfigurationAuthDocsTest(unittest.TestCase):
+ def test_deployment_template_is_inert_and_has_no_seeded_credentials(self):
+ text = (ROOT / ".env.example").read_text(encoding="utf-8")
+ # Copying the reference must not install a shared password or override
+ # existing authentication. Even commented credentials invite reuse.
+ self.assertTrue(all(not line.strip() or line.lstrip().startswith("#")
+ for line in text.splitlines()))
+ self.assertNotRegex(text, r"(?m)^#\s*(?:PULSE_AUTH_(?:USER|PASS)|API_TOKENS?)\s*=")
+ self.assertNotIn("super-secret-password", text)
+ for expected in ("Never overwrite an existing authentication file",
+ "Do not source it", "leave PULSE_AUTH_USER and PULSE_AUTH_PASS unset",
+ "API_TOKEN and API_TOKENS are ignored in v6",
+ "Settings > API Access", "complete bcrypt hash",
+ "does not remove a", "plaintext password from Docker's environment"):
+ self.assertIn(expected, text)
+ # The template sends readers to existing, source-verified recipes;
+ # do not introduce a second credential-file or bootstrap procedure.
+ for target in ("docs/INSTALL.md#step-1-get-the-token",
+ "docs/CONFIGURATION.md#private-docker-authentication-file",
+ "SECURITY.md#api-token-authentication"):
+ self.assertIn(target, text)
+ path, anchor = target.split("#")
+ headings = re.findall(r"^#{1,6}\s+(.+?)\s*$",
+ (ROOT / path).read_text(encoding="utf-8"), re.M)
+ slugs = {re.sub(r"[^\w\s-]", "", heading.lower()).strip().replace(" ", "-")
+ for heading in headings}
+ self.assertIn(anchor, slugs)
+
+ def test_deployment_template_distinguishes_compose_from_runtime_settings(self):
+ text = (ROOT / ".env.example").read_text(encoding="utf-8")
+ compose = (ROOT / "docker-compose.yml").read_text(encoding="utf-8")
+ interpolation = text.split("# Compose interpolation", 1)[1].split(
+ "# Pulse runtime settings", 1)[0]
+ examples = set(re.findall(r"(?m)^#\s*([A-Z][A-Z0-9_]*)=", interpolation))
+ # Tie the documented selectors to the actual bundled Compose file,
+ # rather than implying every .env key reaches the Pulse process.
+ consumed = set(re.findall(r"\$\{([A-Z][A-Z0-9_]*)(?::-[^}]*)?\}", compose))
+ self.assertEqual(examples, consumed)
+ for expected in ("interpolation, not the container's", "does not pass them to Pulse",
+ "not automatically forwarded by Compose", "data directory",
+ "/etc/pulse", "/data inside a container", "PULSE_DATA_DIR",
+ "Deployment-supplied environment values take precedence",
+ "not a Compose interpolation"):
+ self.assertIn(expected, text)
+
def test_no_shared_password_or_secret_in_command_arguments(self):
for name in GUIDES:
with self.subTest(guide=name):