Disk layout: uploads, storage and generated artefacts

A running install writes to seven or eight places outside the database, and several of them grow without any retention policy at all. None of them are enumerated together anywhere else: the backup guidance names frontend/public/uploads/ and stops, and the admin backup screen writes somewhere the backup guidance never mentions.

This is the whole list, what each one is, and what to do when the disk fills.

One rule to read the paths by

Several runtime directories are resolved from process.cwd(), and the backend's working directory is not the same in production and development:

• Under PM2 (pnpm start), the backend and cron apps run with the project root as their working directory.
• In development, the backend runs from backend/.

So a directory the code writes as storage/hb appears at <project-root>/storage/hb on a production install and at backend/storage/hb on a development checkout. Where that applies, both locations are given below. If you are triaging a live server, look at the project root first.

The directories

frontend/public/uploads/

Every upload on the platform lands here, in one subdirectory per category. The category is the dir argument the calling screen passes to POST /api/upload, so the set of directories is whatever screens have been used on your install. A typical one has among others:

avatar/  avatars/  blog/  category/  collectionsbanners/  collectionslogos/
depositMethods/  disputes/  ecosystemTokens/  editor/  faq/  gallery/  icons/
kyc/  legal/  nft/  p2p/  p2ppaymentmethods/  plan/  pool/  product/  project/
settings/  staking/  support/  team/  ticket/  token/  user/

Stored paths are recorded as /uploads/<dir>/<file>, and either process can serve them: Next serves everything under frontend/public/ on port 3000, and the backend intercepts any URL beginning /uploads/ and serves the file itself. Which one answers depends on how your reverse proxy routes /uploads. Both read the same directory, so a missing file is missing from both.

The uploads root is <project-root>/frontend/public/uploads in production and ../frontend/public/uploads relative to backend/ in development, and that is hardcoded. POST /api/upload derives it from process.cwd() and NODE_ENV and reads no environment variable at all; the backend's own /uploads/ handler probes the same two layouts (plus a bare public/) to serve them back. There is no setting that moves this directory.

Nothing prunes this directory. Deleting a record does not always delete its file, so orphans accumulate; there is no built-in sweep and no way to tell an orphan from a live attachment without joining against the database. Treat it as append-only and size the volume accordingly.

backend/storage/

Runtime working directories that are not user content:

The Hummingbot and chart paths are the process.cwd() cases described above; the icon-sync directory is resolved from the backend package root and is therefore always at backend/storage/icon-sync. The P2P attachment directory probes for both layouts, so it is stable at backend/storage/p2p/attachments either way.

backup/ — where the admin backup screen writes

The screen is at /admin/system/database/backup and has no entry in the admin menu — you reach it by typing the URL. Files land in backup/ at the project root, named YYYY_MM_DD_HH_mm_ss.sql, resolved from process.cwd(). That directory is outside both web roots, so the dumps are not downloadable through the site.

The restore route resolves strictly inside this directory. It rejects any value containing a path separator or .., requires the name to end in .sql, and then resolves it against backup/ and confirms the result is still inside. That is why the restore takes a bare filename, not a path — and why moving your dumps somewhere tidier makes them unrestorable from the panel.

backups/nft/

Written by the NFT addon's processNFTBackups scheduled job, which reads per-chain schedules from settings rows keyed nft_backup_schedule_<chain> and runs a full or incremental archive when the schedule's nextRun is due.

The path is BACKUP_PATH if set, otherwise backups/nft under the process working directory — so <project-root>/backups/nft under PM2 and backend/backups/nft in development. BACKUP_ENCRYPTION_KEY encrypts the archives; empty means unencrypted. The service prunes its own old local archives oldest-first by modification time, so unlike backup/ this one is bounded — but only while the job is actually running.

If no NFT backup schedule has ever been configured, this directory will not exist.

lic/

One lic/<productId>.lic per activated product — an AES-256-GCM envelope keyed partly on the host's hardware fingerprint. Small and fixed in size, but two properties matter for disk work:

• It must be writable by the user PM2 runs the backend as. Activation writes atomically into it (temp file, then rename), so a non-writable directory fails activation rather than corrupting anything.
• Do not back it up and do not restore it onto other hardware. It will not decrypt, and the extension manager's licenseVerified flag is an existence check, so a stale file reads as licensed while every route 403s. Re-activate instead — Licences and activation.

ls lic/ is also the fastest inventory of which products this install has ever activated: each filename is a product id.

updates/ and .update-backup-*

updates/ at the project root is where a release ZIP is streamed before it is extracted. It is deleted on success and on failure, so a ZIP sitting there means a download that neither completed nor cleaned up.

.update-backup-<timestamp> at the project root is the snapshot the extractor takes of every file it is about to overwrite. It is removed on a successful extraction and consumed by the rollback on a failed one, so a leftover directory means an update that ended badly. Delete it only once you have confirmed the platform is healthy on the new version — until then it is the pre-update tree.

Both can be large: a snapshot of an overwritten tree is roughly the size of the files the release touches.

data/chart, data/chart-fx, data/chart-dex

Gzipped candle caches written by the exchange chart builder and by the forex and DEX addons, one subdirectory per symbol. Resolved from the process working directory, so <project-root>/data/... under PM2. Pure cache — deleting them costs a rebuild of the affected charts and nothing else.

backend/ecosystem/wallets/

Master wallet exports, one JSON file per chain. Gitignored and in no release package. Small, static, and belongs in your backup — it is on the "not covered by anything in the product" list in Updating for a reason.

~/.pm2/logs/

Every line the three PM2 apps write to stdout and stderr, as backend-out.log, backend-error.log and the same pair for frontend and cron, in the home directory of the user that owns the PM2 daemon.

Nothing rotates these. There is no log rotation configured in the product and no application log directory — the backend logs to the console and PM2 captures it. On a busy install with LOG_LEVEL=debug these are frequently the largest files on the box.

du -sh ~/.pm2/logs
pm2 flush              # truncate every log file, immediately

pm2 flush is safe and is the fastest space you can recover on a full disk. For a permanent fix, install PM2's log-rotate module or point logrotate at the directory.

What to back up, what a build regenerates, what is safe to prune

When a disk fills

Work down this list — it is ordered by how much space it usually returns for how little risk.