Back to Integration Guide Public FileVault setup reference
Denning FileVault Guideline

FileVault setup guide managed from DCC for new tenants, existing tenants, and legacy FTP onboarding

This guide explains the agreed operating model: FileVault setup is managed from DCC (Denning Command Center) by platform admins, auth.appregisteredserver is bootstrap-only, and FileVault itself remains the runtime source of truth.

Runtime truth sysdes via fv_servers, fv_files, fv_directories
Bootstrap source denningonline.appregisteredserver on the auth connection
Target experience Admins configure storage once, import old files if needed, then use FileVault normally

Source of truth

Use auth only to discover legacy tenant storage. Once a tenant is onboarded into FileVault, all runtime decisions come from FileVault tables in sysdes.

Connection Database Table Purpose
auth denningonline appregisteredserver Bootstrap-only registry for tenant FTP/FileSystem host, port, directory, and legacy storage hints.
centralized sysdes fv_servers Active provider per server and provider configs in storage_config.
centralized sysdes fv_files File metadata only. Each row knows the file path and the provider used for that file.
centralized sysdes fv_directories Explicit folder metadata. Some folders are inferred from file paths, but created folders can also live here.
Rule
After FileVault setup is saved, later provider migration must use FileVault-managed configs from fv_servers. It must not go back to appregisteredserver.Ftp* as the source of truth.

Tenant scenarios

New tenant

No legacy tenant storage to import

  1. Platform admin opens the DCC FileVault page at /tenants/{serverCode}/filevault.
  2. Choose system if tenant should start on Denning S3.
  3. Or choose ftp/sftp if tenant should start on tenant-hosted storage.
  4. Save setup. This writes into sysdes.fv_servers.
  5. New uploads use the active provider immediately.
Existing tenant

Legacy files already exist on tenant server

  1. Platform admin opens the DCC FileVault page at /tenants/{serverCode}/filevault.
  2. Bootstrap metadata is detected from auth.appregisteredserver.
  3. Choose ftp or sftp and fill any missing credentials.
  4. Save setup. Active provider becomes tenant storage.
  5. Use the DCC FileVault page to start the legacy import, creating missing fv_files and fv_directories.
  6. Later, migrate to system through the DCC FileVault page if desired.
Do not skip import for legacy tenants
Storing FTP credentials alone does not make old files appear in FileVault. Old files need metadata rows in fv_files before FileVault can list them.

FTP / FileZilla rule

The root exposed to FileVault must contain the tenant folder named with the server code.

Correct

Expose the parent folder

  • Real path on tenant server: C:\DenningOnlineFolder\TS0004\...
  • FileZilla user root: C:\DenningOnlineFolder
  • FTP-visible path: /TS0004/...
  • Matches FileVault path contract: server_code/...
Wrong

Do not expose the tenant folder itself

  • FileZilla user root: C:\DenningOnlineFolder\TS0004
  • FTP-visible path becomes: /documents/...
  • FileVault expects: TS0004/documents/...
  • Result: path mismatch and broken legacy import.

Firewall & passive mode requirements

FileVault connects to tenant FTP servers from the production server. FTP uses two types of connections that must both be allowed.

Control channel

Port 21 (or custom)

  • Standard FTP command port
  • Used for login, directory listing commands, file transfer commands
  • If the connection test passes, this port is open
Data channel (passive mode)

Ports 50000–51000 (configurable)

  • Every file listing and transfer opens a separate data connection on a random high port
  • If port 21 works but import times out, the passive ports are blocked
  • Must be opened on the tenant's firewall for connections from 13.229.209.4 (FileVault production server)
How to configure passive ports on FileZilla Server
FileZilla Server 0.x (Windows): Edit → Settings → Passive mode settings → Check "Use custom port range" → Set 50000–51000
FileZilla Server 1.x (macOS/Linux): Server → Configure → FTP over TLS → Passive mode tab → Set port range

Then open inbound TCP 50000–51000 on the firewall for source IP 13.229.209.4.
Common symptom
"Connection Successful" in DCC but "Import Failed: ftp_rawlist(): Connection timed out" means the passive data ports are blocked. The control channel (port 21) works but data transfers cannot complete.

Operator flow

1
Check bootstrap source
See whether auth.appregisteredserver has usable FTP/FileSystem data for the server.
2
Open DCC FileVault page
Storage setup is managed from DCC by platform admins. Go to DCC → Tenants → [Server Code] → FileVault. Tenant users can see storage status in ERP but cannot configure or import.
3
Save active provider
Saving setup writes provider configuration into sysdes.fv_servers.storage_config and updates fv_servers.storage_provider.
4
Import old files if tenant is legacy
Use the DCC FileVault page to start the import. This indexes old tenant files into fv_files and fv_directories. The artisan command is available as a fallback.
5
Normal operations
New uploads use the active provider. Later migrations between providers should be done via DCC FileVault page and FileVault configs, not auth.

Screenshot-like walkthrough

These are visual mockups of the intended UI, not actual screenshots.

ERP / Settings / Storage (read-only status view) TS0004

System Storage

Using System Storage
Scope Denning-managed
Provider System Storage
S3
System Storage
Active · Connected
Meaning

Storage settings view (ERP)

  • Tenant users see current storage status in ERP but cannot configure or import from here.
  • The page shows known provider configs from FileVault in read-only mode.
  • Configuration and import are done from the DCC FileVault page by platform admins.
DCC / Tenant FileVault Management Platform admin only

Tenant FileVault Management

Configure FTP → Test Connection → Save → Import → Re-sync. Managed from DCC at /tenants/{serverCode}/filevault.
System Storage
Denning-managed AWS S3
FTP Server
Tenant-hosted FileZilla
SFTP Server
SSH/SFTP tenant storage
Legacy storage detected
Legacy FTP storage was detected from the auth registry. Missing details: username, password.
100.64.0.4
21
filevault
••••••••••••
C:/DenningOnlineFolder
Existing files still need to be indexed into FileVault after setup. Use the Import button on this DCC page to start indexing.
Meaning

DCC FileVault page

  • Platform admins manage tenant FileVault configuration from DCC at /tenants/{serverCode}/filevault.
  • Recommended provider is derived from bootstrap metadata. Missing fields are filled in by the admin.
  • Saving setup writes the final working config into fv_servers.storage_config.
  • Once saved, FileVault becomes the system of record for provider config.
  • Import and re-sync are triggered directly from this DCC page.
DCC / Tenants / TS0004 / FileVault Platform admin
Discovered files 1,352
Directories to create 402
Fallback: The artisan command php artisan filevault:import-legacy-storage TS0004 is still available for CLI use if needed.
Legacy only

One-time indexing step

  • Needed only for tenants that already have files on their own server.
  • Primary method: Go to DCC → Tenants → [Server Code] → FileVault → Start Import.
  • Does not replace provider setup; it complements it.
  • Creates metadata records so FileVault can list, browse, and operate on old files.

Import methods

Primary: DCC UI

Go to DCC → Tenants → [Server Code] → FileVault → click Start Import. The DCC page handles discovery, preview, and execution in one workflow.

Fallback: Artisan command

php artisan filevault:import-legacy-storage TS0004 --dry-run
php artisan filevault:import-legacy-storage TS0004
If the tenant is already FileVault-configured with a working FTP/SFTP config in fv_servers.storage_config, the command can resolve the existing config directly. Legacy FTP import no longer supports shared fallback credentials; missing tenant-specific FTP credentials must be saved in FileVault first.

Quick checklist

Existing tenant
  • Install Tailscale on tenant server.
  • Install FileZilla Server or provide SFTP access.
  • Expose parent folder containing server_code folder.
  • Save setup via DCC FileVault page.
  • Use DCC FileVault page to start legacy import.
New tenant
  • Decide between system and ftp/sftp.
  • Save active provider.
  • No import needed if there are no old files.
  • Use FileVault normally.
Later migration
  • Use DCC FileVault page migration flow.
  • Migrate between FileVault-managed providers.
  • Ignore appregisteredserver.Ftp* after onboarding.