Database schema

The tables in VaultPanel's MariaDB database by area, the migrations that add them, how secrets are stored at rest and how the audit log is protected.

Last updated

The panel keeps its state in MariaDB 10.6 or newer (or MySQL 8) through Knex. Migrations are in database/migrations; npm run db:migrate applies them and then syncs the built-in roles and permissions from shared/src/permissions.js. On an installed panel, vaultpanel update runs them for you.

  • IDs are UUIDs generated by the application, except the high-volume append tables (audit_logs, server_metrics, job_logs), which use auto-increment integers.
  • All timestamps are UTC with millisecond precision.
  • PostgreSQL is not supported.

This is the panel's own database, separate from the MariaDB the panel installs on servers for websites and apps. On an installed panel it runs in Docker on 127.0.0.1:3307.

Accounts and access

TablePurpose
usersAccounts: password hash (scrypt), encrypted TOTP secret, lockout counters, soft delete.
roles, permissions, role_permissionsBuilt-in roles and their permissions, synced from code.
user_rolesRole assignments (the interface assigns one role per user).
teams, team_membersSchema only, for later features.
sessionsBrowser sessions; only a SHA-256 of the cookie value is stored.
password_reset_tokensInvite and reset links: hashed, single use, expiring.
user_recovery_codesTwo-factor recovery codes.
api_tokensAPI tokens: owner, scopes, expiry; only the token's SHA-256.
audit_logsThe append-only audit trail.
settingsPanel settings; secrets in it are stored encrypted.
email_messagesEmail the panel sends itself (invites, resets, alerts, tests), kept for retries; the body is encrypted.

Servers, monitoring and jobs

TablePurpose
serversManaged servers with their latest system information, service and filesystem snapshots, web stack, Docker summary, security summary and self-check report. Soft delete.
server_enrollment_tokensOne-time agent enrollment tokens (hashed).
server_agentsRegistered agents and their Ed25519 public keys; revocation.
server_metricsTelemetry samples, kept 7 days by default (VAULTPANEL_METRICS_RETENTION_DAYS).
server_metrics_hourlyHourly averages (and CPU maximum) rolled up from server_metrics, kept 90 days by default.
alert_rulesThresholds: metric, threshold, how long it must hold, severity, optional server or service.
alert_eventsOne row per alert: pending, firing, resolved, acknowledgement. A unique key allows one open event per rule, server and subject. Resolved alerts are kept 90 days by default (VAULTPANEL_ALERT_HISTORY_DAYS).
jobsOperations requested for servers: type, status, attempts, timeouts, output, error, and the record they belong to (resource_type, resource_id).
job_logsLog lines streamed by agents and the panel for each job.
server_groups, server_group_membersServer groups.
bulk_actions, bulk_action_targetsOne action across a group, and one row per server.
terminal_sessionsTerminal sessions owners opened; recordings are asciicast files in the panel's data folder.

The monitoring migration seeds five alert rules (CPU, memory, disk, server offline, service down); later migrations add Website down and Server self-check failed. All can be edited or deleted.

Websites, DNS and email

TablePurpose
websitesWebsites: type, server, settings, pending changes, Git deploy settings, uptime status, disk use.
website_domainsEach website's domains, with the primary one.
ssl_certificatesCertificates: issuer, expiry, renewal settings, the DNS provider a wildcard was checked through.
website_deploymentsDeployments of static websites from Git.
website_environment_variablesEnvironment variables for those deployments' build commands, encrypted.
website_checks, website_incidentsUptime checks and stretches of downtime, kept 30 days by default (VAULTPANEL_UPTIME_HISTORY_DAYS).
cms_installsApps put in a website by the app installer (WordPress, Joomla, Drupal, Laravel), with their database.
file_uploads, file_downloadsLarge file-manager uploads and downloads passed through the panel in pieces.
dns_zones, dns_recordsDNS zones served by BIND on the panel's servers, and their records.
dns_providersCloudflare and Namecheap accounts used for wildcard certificates; the secret is encrypted.
mail_servers, mail_domains, mailboxes, mail_forwardersEmail hosting: the mail server on each server, its domains, mailboxes and forwarders.

Apps, databases and containers

TablePurpose
applicationsApps: runtime, repository, commands, port, copies, CPU and memory limits, the current release, process state.
environment_variablesEach app's environment variables, encrypted.
deploymentsEach deployment of an app: trigger, commit, stage, status, log.
databasesMariaDB databases on the servers, with their size and the app or website they belong to.
database_users, database_user_grantsDatabase users, with encrypted passwords, and their access to databases.
containersDocker containers deployed by the panel, with their settings; environment values are encrypted.

Backups, cron and webhooks

TablePurpose
backupsBackups of websites, apps and databases: status, size, SHA-256, where they are kept.
backup_schedulesBackup schedules with how many to keep.
backup_restoresRestores and their safety backups.
backup_storagesOff-server destinations: S3-compatible buckets and SFTP servers.
cron_jobs, cron_runsCron jobs and the result of each run.
webhooks, webhook_deliveriesWebhooks and each delivery, with retries. URLs and signing secrets are encrypted.

Hosting, assistant and plugins

TablePurpose
hosting_plansPlans: limits, app caps, price, billing cycle, server group.
customersHosting accounts: plan, server, billing id, status, what suspending turned off.
customer_portsEach customer's own app ports per server.
api_keysBilling API keys; only the key's SHA-256.
assistant_conversations, assistant_messages, assistant_actionsAI assistant conversations, every model reply, tool call and result, and proposed actions.
pluginsInstalled plugins: manifest, approved scopes, the token's SHA-256 and the encrypted signing secret.
plugin_directoriesPlugin directories and the last copy read.

Migrations

MigrationAdds
20261003000001_foundationAccounts, servers, agents, metrics, jobs, the audit log, settings.
20261004000001_monitoringHourly metrics, alert rules and events.
20261004000002_websitesWebsites, domains, SSL certificates.
20261004000003_applications_databasesApps, environment variables, deployments, databases and users.
20261004000004_backups_cron_webhooksBackups, schedules, restores, cron jobs, webhooks.
20261004000005_local_serverMarks the panel's own server.
20261004000006_securityThe servers' security summary, two-factor recovery codes, app CPU and memory limits.
20261005000001_multi_serverServer groups and bulk actions.
20261005000002_hostingPlans, customers, billing API keys.
20261005000003_assistantThe AI assistant.
20261005000004_containersContainers.
20261005000005_api_tokensAPI tokens.
20261005000006_pluginsPlugins.
20261006000001_customer_portsCustomer app ports.
20261006000002_backup_storageOff-server backup storage.
20261006000003_app_instancesSeveral copies of an app.
20261007000001_dns_zonesDNS zones and records.
20261007000002_mailEmail hosting.
20261007000003_custom_nginxCustom NGINX rules for websites.
20261008000001_cms_installsThe app installer.
20261008000002_panel_emailPanel email.
20261012000001_site_git_deployStatic website Git deploy.
20261012000002_website_environmentWebsite environment variables.
20261012000003_ssl_renewalSSL renewal settings.
20261012000004_customer_dnsName servers and DNS zones for customers.
20261012000005_file_uploadsLarge uploads.
20261013000010_file_downloadsLarge downloads.
20261013000101_terminal_recordingsTerminal sessions and recordings.
20261013000140_plugin_directoriesPlugin directories.
20261019000001_website_spaSingle-page app websites.
20261019000101_signed_git_webhooksSigned push-to-deploy webhooks.
20261019000102_app_zero_downtimeZero-downtime reloads.
20261031000001_dns_providersDNS providers for wildcard certificates.
20261031000002_website_uptimeWebsite uptime monitoring.
20261031000003_server_self_checkThe server self-check report.
20261101000001_database_website_linkLinking a database to a website.

Secrets at rest

  • Passwords are scrypt hashes.
  • Session, enrollment and reset tokens, API tokens, plugin tokens, push-to-deploy tokens and billing API keys are stored as SHA-256 hashes, so they are shown once.
  • TOTP secrets, the job-signing private key, app and website environment variables, database user passwords, container environment variables, webhook URLs and signing secrets, plugin signing secrets, DNS provider secrets, the assistant's API keys and panel email bodies are encrypted with AES-256-GCM, with keys derived from VAULTPANEL_SECRET_KEY.
  • Passwords sent to the agent are removed from the stored job when it finishes.

Audit log protection

On MariaDB and MySQL, triggers reject every UPDATE and DELETE on audit_logs. TRUNCATE and DROP bypass triggers, so run the panel with a database user that lacks DROP where you can.