Skip to content

Reporting bugs

How to send a Vloud-engine bug report from your dashboard, what's in the diagnostic bundle, and what happens after you click Submit.

Where to report from

Two entry points, both in the dashboard:

  • Help → Report a bug (top-right ? icon, on every authenticated page). The general-purpose entry point.
  • AI Doctor → Report bug (inside a failed deploy’s AI analysis when the analysis is classified as a Vloud-platform issue rather than a customer app issue). One-click — the analysis is auto-attached as the report body.

Both paths submit to the same place. You don’t need to file anything on GitHub or email anyone — it’s all in-product.

What the form asks for

  • Title. One-line summary. Customers who provide a precise title (“Deploy fails when package.json has inline workspaces”) get triaged faster than ones who write “deploy broken”.
  • Description. Steps to reproduce, expected vs. actual, error messages.
  • Severity. Low (minor / cosmetic), Medium (impaired functionality), High (broken or data risk).
  • Affected module. Optional dropdown — auth, billing, deploy, domains, dns, ssl, email, security, monitoring, updates, license/trial, backups, storage, tenant, reseller, cli, other.
  • Include diagnostic bundle (on by default). See below.

What’s in the diagnostic bundle

The bundle is a 50 MB-capped tarball collected fresh per report. Generated by services/support-bundle.ts in the engine and uploaded as a typed attachment to the upstream bug report.

Included

  • Manifest. Hostname (truncated), engine version, generated_at timestamp.
  • OS info. Distro name + version, kernel.
  • Environment — redacted. Every = value whose key matches password, token, jwt, signing_key, encryption_key, etc. is replaced with [REDACTED] before the bundle is written.
  • Recent engine logs. Last ~1000 lines of journalctl -u vloud.
  • Audit log. Last 100 audit_events rows, also passed through the redaction filter.
  • Health snapshot. Output of the existing /api/health aggregator.
  • Migration history. Applied migration names + timestamps.
  • Queue state. BullMQ + sqlite-queue depths, recent job summaries.
  • Package versions. dpkg --get-selections output for vloud-relevant packages.
  • License claims. Tier, status, limits, current usage. Not your license_secret — that’s the rotating HMAC key, never bundled.
  • Trial state. Trial expiry timestamp, state (active / expired / tampered / licensed).

Excluded by design

  • Your tenant data, app source code, mailboxes, database rows.
  • Customer email addresses (we redact obvious patterns in audit payloads).
  • Anything in /etc/vloud.env beyond the keys named above — the JWT secret, machine_id HMAC, and any other credentials never appear in the bundle.

The redaction is fail-closed: if a key looks like it might be a secret and matches any deny-list pattern, it gets [REDACTED] rather than risk a leak. The success panel after submission shows the redaction counters so you can confirm what was suppressed.

What happens after Submit

  1. Local persistence. Your engine writes the report to its local SQLite (table vloud_bug_reports), status pending, with a content-hash for dedup.
  2. Upload (≤10 min). The engine’s scheduler runs every 10 minutes; on its next tick it POSTs your report to Vloud’s upstream license-server at /v1/platform-bugs/report. Auth: JWS-HMAC over your license_secret (or G1 cert-chain when both sides are configured).
  3. Upstream dedup. The cloud side keys reports by (license_id, content_hash). Repeated reports of the same content collapse — repeated re-occurrences bump an occurrences counter so triage can prioritise by impact.
  4. Triage. Vloud engineering sees the report on the admin dashboard with your license, install, engine version, and the diagnostic bundle attached. Status moves through new → investigating.
  5. Fix. When a fix ships in a release, the ticket gets a fixed_in_version stamp and status flips to fixed.
  6. Notification. On your next engine sync (≤10 min), the bug-report row gets the new status. A green fix-notification banner appears at the top of your dashboard: “Your reported bug ‘X’ was fixed in v1.4.2.” One-click Update now routes to System Updates with that version highlighted.
  7. Auto-verify. Once you apply the update, the next heartbeat (≤6h, or immediate if you restart the engine) carries your new binary_version. The cloud side auto-transitions the ticket to verified. Your local My Tickets page shows it as Resolved.

The whole loop — report to resolved — runs without staff interaction after the fix release is published. The customer learns about the fix in their dashboard within minutes; the verification confirms automatically.

Tracking your reports

Help → My tickets lists every bug you’ve reported from this server. Each row shows:

  • A friendly status — Queued / Received / Investigating / Fixed (update available) / Resolved / Won’t fix / Submission failed / Already reported.
  • Fix-version badge when known.
  • Engine version you were on when you reported (helpful when comparing against the fix-version).
  • “Updated N minutes ago” — auto-refresh every 30s.

Expanding a row reveals the full description, the structured context the report was submitted with (severity, affected module, browser path, user agent), and the attached diagnostic bundle filename + size.

Privacy & what we keep

Diagnostic bundles are bound to your license_id on our side and used solely for triage. They’re retained for 90 days, then deleted. We don’t train models on them or share them with third parties.

If you spot something in a bundle that shouldn’t be there (a redaction the deny-list missed), email security@vloud.app — those reports are themselves triaged with priority.

Pre-submission privacy review

Generated bundles land at /var/lib/vloud/support-bundles/<timestamp>.tgz on your server. The bundle isn’t uploaded until the report POST succeeds — if you want to inspect the bytes before submission, cancel the modal after “Collecting diagnostics…” finishes (you can also click Submit without bundle after 20s) and review the tarball locally first:

tar -tzf /var/lib/vloud/support-bundles/vloud-support-*.tgz | head -20
tar -xzOf /var/lib/vloud/support-bundles/vloud-support-*.tgz manifest.json

Re-submit through the modal when you’re ready, or open the tarball and remove any file before submission with a custom path:

tar --delete -f bundle.tgz path/inside/bundle

Reporting a security vulnerability

Don’t file security issues through the in-product bug reporter. Email security@vloud.app directly. Security reports get a separate triage channel with a 24-hour acknowledgment SLA.