Environment Reference

nextExplorer is configured almost entirely through environment variables. The backend (backend/src/config/env.js) centralizes the defaults you see here. Use this reference when you want to tune ports, paths, auth, integrations, or feature flags.

Secrets

Every credential listed below can be read from a file instead of the environment. Append _FILE to the variable name and point it at the file holding the value:

Variable	File variant
SESSION_SECRET (or AUTH_SESSION_SECRET)	SESSION_SECRET_FILE
AUTH_ADMIN_PASSWORD (or ADMIN_PASSWORD)	AUTH_ADMIN_PASSWORD_FILE
OIDC_CLIENT_SECRET	OIDC_CLIENT_SECRET_FILE
ONLYOFFICE_SECRET	ONLYOFFICE_SECRET_FILE
COLLABORA_SECRET	COLLABORA_SECRET_FILE

docker inspect prints every environment variable a container was started with, so a secret passed inline is readable by anyone who can reach the Docker daemon and stays in the container's stored configuration. Mounting it as a file keeps it out of both:

services:
  nextexplorer:
    environment:
      ONLYOFFICE_SECRET_FILE: /run/secrets/onlyoffice_secret
    secrets:
      - onlyoffice_secret

secrets:
  onlyoffice_secret:
    file: ./secrets/onlyoffice_secret

The plain variable wins when both are set. Surrounding whitespace is stripped, so a file written with echo secret > file behaves as expected. A _FILE naming a missing or empty file stops the server at startup instead of quietly running without the secret.

Server & networking

Variable	Default	Description
PORT	3000	Port the Express API and frontend listen on inside the container.
ADDRESS	0.0.0.0	Interface the server binds to. Leave it alone unless you have a reason to reach only one network.
HTTP_TIMEOUT	0	Node.js HTTP requestTimeout (ms). Use 0 to disable (avoids the Node 5-minute default that can abort large uploads).
UPLOAD_INACTIVITY_TIMEOUT	120000	Classic upload inactivity timeout (ms). If no bytes are received for this delay, the request is aborted and .uploading is cleaned up. Use 0 to disable.
UPLOAD_CHUNKED_ENABLED	false	Default for the admin upload setting. When enabled, browser uploads use TUS chunked transfer instead of one large request.
UPLOAD_CHUNKED_AUTO_FALLBACK	false	Default for the admin setting. When direct (XHR) uploads are used, automatically switch to chunked with a safe size if a reverse proxy rejects the body; the working size is remembered per client origin.
UPLOAD_CHUNK_SIZE	8M	Default TUS chunk size. Supports byte-size suffixes such as 4M, 16M, or 64M; keep it below reverse proxy body limits.
MAX_CHUNK_SIZE_MIB	512	Upper bound (MiB) an admin may set for the chunk size; caps the settings slider/input and clamps saved values. Hard ceiling of 512 MiB.
UPLOAD_STORAGE_RESERVE	64M	Free-space reserve kept when accepting uploads. An upload is rejected with 507 when the destination — or, for a chunked upload, the temporary storage — cannot fit what is coming plus this reserve. The reserve is what keeps a full volume from taking the database down with it, where /config shares the filesystem.
TUS_UPLOAD_DIR	<CACHE_DIR>/tus-uploads	Temporary storage directory for TUS chunked uploads. Put it on a volume large enough for the biggest in-progress uploads, and — importantly — on the same filesystem as the destination: chunks are assembled here and the finished file is then moved into place, which is instant within one filesystem but becomes a full byte-for-byte copy across two. With the default under CACHE_DIR, a multi-gigabyte upload appears to stall at 100% while that copy runs.
TUS_INCOMPLETE_UPLOAD_TTL_MS	3600000	Age after which an abandoned chunked upload is deleted from the temporary directory (1 hour).
TUS_CLEANUP_INTERVAL_MS	600000	Delay between sweeps looking for abandoned chunked uploads (10 minutes).
PUBLIC_URL	none	External URL (no trailing slash). Drives cookie settings, CORS defaults, and derived callback URLs (OIDC/OnlyOffice).
INTERNAL_URL	none	Additional comma-separated origins. They are accepted by CORS and OIDC returns to the configured origin where login began.
TRUST_PROXY	loopback,uniquelocal when PUBLIC_URL is set	Express trust proxy configuration. Accepts false, numbers, CIDRs, or lists.
CORS_ORIGIN, CORS_ORIGINS, ALLOWED_ORIGINS	empty	Comma-separated list of allowed CORS origins. Defaults to the PUBLIC_URL / INTERNAL_URL origins when set. When none of them is set, no cross-origin caller is allowed — same-origin use (frontend and API on one host) is unaffected. Use * only if you deliberately want to reflect any origin.

Logging & debugging

Variable	Default	Description
LOG_LEVEL	info (or debug when DEBUG=true)	Application log level: trace, debug, info, warn, or error.
DEBUG	false	When true, forces LOG_LEVEL=debug and shows more verbose diagnostics (including more detailed error output in development).
ENABLE_HTTP_LOGGING	false	When true, enables HTTP request logging in the backend (use with centralized log collection in production).
PERFORMANCE_DIAGNOSTICS_ENABLED	false	Logs process CPU, Node and cgroup memory, event-loop delay, active resources, thumbnail queues, and folder-size activity when pressure is detected.
PERFORMANCE_DIAGNOSTICS_INTERVAL_MS	15000	Sampling interval in milliseconds; minimum 5000.
PERFORMANCE_DIAGNOSTICS_LOG_EVERY_INTERVAL	false	Set to true to log every sample during a short investigation.
PERFORMANCE_DIAGNOSTICS_CPU_THRESHOLD	75	CPU percentage that triggers a diagnostic entry.
PERFORMANCE_DIAGNOSTICS_RSS_THRESHOLD_MB	768	Node RSS threshold in MiB that triggers a diagnostic entry.
PERFORMANCE_DIAGNOSTICS_EVENT_LOOP_DELAY_MS	250	p99 event-loop delay threshold in milliseconds that triggers a diagnostic entry.

Paths & volumes

Variable	Default	Description
VOLUME_ROOT	/mnt	Root directory that houses all mounted volumes.
CONFIG_DIR	/config	Location for SQLite, app-config.json, extensions, and settings.
CACHE_DIR	/cache	Location for thumbnails, ripgrep indexes, and temporary data.
USER_ROOT	<VOLUME_ROOT>/_users when unset	Root directory for per-user personal folders. Each authenticated user gets their own subdirectory under this path.
USER_FOLDER_NAME_ORDER	id,username,email_local	Preference order for per-user folder names (e.g. set username,id to reuse /home/<username> when USER_ROOT=/home). A name is given once and kept; an account whose preferred name is already taken takes the next in the order, so two accounts never share a folder. See personal folders.
HIDDEN_FILE_PATTERNS	.,regex:\\.download$,regex:\\.uploading$	Comma- or space-separated hidden filename patterns used by directory listings, volume pickers, and search. Plain values are fast filename prefixes, e.g. .,@ hides dotfiles and Synology @... entries. Advanced entries can use regex:<source> or /source/flags; by default, the artifacts of a transfer in progress — .download while a file is being fetched, .uploading while one is being written — are hidden through this same configurable policy. Overriding this variable replaces the defaults, so include those two patterns in your own list to keep them hidden. Set to an empty value to disable pattern hiding.

Copying & moving

Variable	Default	Description
COPY_PRESERVE_PERMISSIONS	true	Whether a copy keeps the source file's permissions. Preserving them means a chmod on the destination, which some filesystems refuse — a ZFS dataset with aclmode=restricted, where new files must inherit the directory's ACL untouched. Such a copy is retried without preserving them automatically; set this to false where it is always refused, to skip the attempt.
FILE_TRANSFER_ENGINE	native	Set to stream to copy in the application rather than through rsync. Slower on large transfers; useful where a native tool is unavailable or unwanted.

Folder-size index

Variable	Default	Description
FOLDER_SIZE_MODE	off	Enables indexed folder sizes: full is recursive, shallow counts direct entries only.
FOLDER_SIZE_EXCLUDE_PATHS	empty	Comma- or newline-separated paths relative to VOLUME_ROOT excluded from folder-size scans.
FOLDER_SIZE_RECONCILE_BATCH	100	Number of indexed folders checked per periodic reconciliation page.
FOLDER_SIZE_RECONCILE_PAUSE_MS	200	Delay between reconciliation pages, used to smooth background I/O.
FOLDER_SIZE_RECONCILE_MAX_DIRECTORIES	200	Maximum indexed folders checked by one scheduled reconciliation slice. 0 restores a full sweep.
FOLDER_SIZE_IO_TIMEOUT_MS	30000	Deadline for one indexed folder-size filesystem operation; 0 disables this protection.
FOLDER_SIZE_MAX_STALLED_IO	2	Timed-out folder-size operations allowed before the indexer pauses further filesystem work.
FOLDER_SIZE_SUBTREE_BATCH	reconciliation batch	Metadata checks per batch while recovering a folder tree created or changed outside NextExplorer.
FOLDER_SIZE_CONCURRENCY	6	Parallel folder-size scans on local storage.
FOLDER_SIZE_NETWORK_CONCURRENCY	2	Parallel folder-size scans on network storage, where seek latency dominates.
FOLDER_SIZE_FLUSH_MS	3000	Delay before pending folder-size updates are written to the index.
FOLDER_SIZE_RECONCILE_MS	0	Fixed interval between reconciliation sweeps. 0 uses the adaptive interval below.
FOLDER_SIZE_RECONCILE_MIN_MS	900000	Shortest adaptive reconciliation interval (15 minutes).
FOLDER_SIZE_RECONCILE_MAX_MS	43200000	Longest adaptive reconciliation interval (12 hours).
FOLDER_SIZE_REBUILD	false	Drop and rebuild the folder-size index at startup.
FOLDER_SIZE_SUBTREE_PAUSE_MS	reconciliation pause	Delay between targeted recovery batches. Leave unset to inherit the reconciliation pacing.
FOLDER_SIZE_SUBTREE_SLOW_LOG_MS	5000	Duration after which a targeted recovery emits one info performance summary.

Targeted subtree recoveries are always serialized so concurrent external changes cannot race their SQLite ancestor updates. The batch and pause settings govern their I/O intensity without affecting the normal list-view reads.

Authentication

Variable	Default	Description
AUTH_ENABLED	true (in prod)	Toggles authentication; disabling makes all APIs public. Deprecated: use AUTH_MODE=disabled instead.
AUTH_MODE	both (or local if OIDC not configured)	Controls which authentication methods are available: local (username/password only), oidc (SSO only), both (both methods), or disabled (skip login entirely, same as AUTH_ENABLED=false).
SESSION_SECRET, AUTH_SESSION_SECRET	auto-generated	Cryptographic secret used by Express to sign and encrypt session cookies and related tokens. In production, set this to a long, random, stable value (at least 32 characters) so sessions remain valid across restarts and multiple replicas; if left unset, a new random secret is generated on each start and all users will be logged out after every restart.
SESSION_MAX_AGE_DAYS	30	Duration (in days) that user sessions remain valid. Sessions persist across browser restarts and server reboots. Set to a lower value (e.g., 7) for stricter security, or higher (e.g., 90) for convenience. Applies to both local authentication and OIDC sessions.
AUTH_MAX_FAILED	5	Failed login attempts before temporary lockout.
AUTH_LOCK_MINUTES	15	Lockout duration in minutes when max failures reached.
AUTH_ADMIN_EMAIL	none	Optional first-run bootstrap for local auth: when set with AUTH_ADMIN_PASSWORD, the backend creates an admin user on startup (and the setup wizard is skipped).
AUTH_ADMIN_PASSWORD	none	Password used for AUTH_ADMIN_EMAIL bootstrap. If a user already exists with the same email, this value overrides/resets the local password on startup. (Minimum 6 chars; avoid leaving this set unless you want the password enforced on every restart.)

OIDC & SSO

Variable	Default	Description
OIDC_ENABLED	false	Enable Express OpenID Connect authentication flow.
OIDC_ISSUER	none	IdP issuer URL (discovery).
OIDC_AUTHORIZATION_URL, OIDC_TOKEN_URL, OIDC_USERINFO_URL	none	Optional overrides for discovery endpoints.
OIDC_LOGOUT_URL	none	Optional custom IdP logout URL. When set, logout requests redirect to this URL with a post_logout_redirect_uri parameter (OIDC standard). If not set, logout only clears the local session.
OIDC_CLIENT_ID, OIDC_CLIENT_SECRET	none	IdP credentials.
OIDC_CALLBACK_URL	${PUBLIC_URL}/callback when PUBLIC_URL is set	Explicit canonical callback path; defaults to /callback under PUBLIC_URL. Register every <INTERNAL_URL>/callback with the IdP when internal origins are configured.
OIDC_SCOPES	openid profile email	Default scopes; add groups to propagate group claims.
OIDC_ADMIN_GROUPS	none	Space/comma-separated names that grant admin rights when found in groups, roles, or entitlements.
OIDC_REQUIRE_EMAIL_VERIFIED	false	When true, requires the IdP to verify the user's email before allowing user creation or auto-linking. Some providers like newer Authentik versions set email_verified to false by default.
OIDC_AUTO_CREATE_USERS	true	When false, the user must already exist in the nextExplorer database (local or previously OIDC-linked), otherwise OIDC login is denied.

Upload & archive limits

These are safety ceilings, not tuning knobs: they exist so a single request cannot fill the volume. The defaults are high enough for normal use.

Variable	Default	Description
MAX_DIRECT_UPLOAD_SIZE	64GB	Largest single file accepted by a direct (non-chunked) upload, e.g. 10GB. Chunked/TUS uploads are bounded by their storage guard.
MAX_FILES_PER_UPLOAD	50	Maximum number of files in one direct upload request.
MAX_JSON_BODY_SIZE	8MB	Largest JSON request body accepted. These carry lists of paths — deleting or copying a few thousand files needs a few hundred kB — not file content. Saving from the text editor is the exception: the file travels in one, so leaving this unset lets it rise to carry whatever EDITOR_MAX_FILESIZE opens, while a value set here is a ceiling that is kept and lowers the editor instead.
BULK_DELETE_CONCURRENCY	available CPU count	Entries removed at once during a bulk delete. Raise it on storage that answers slowly (a bind-mounted volume can need ~60x longer per operation than a native filesystem); lower it if the disk is the bottleneck rather than the latency.
MAX_EXTRACTED_ARCHIVE_SIZE	32GB	Refuse to extract an archive whose declared uncompressed size exceeds this ("zip bomb" guard).
MAX_ARCHIVE_ENTRIES	100000	Refuse to extract an archive holding more entries than this.

Feature toggles

Variable	Default	Description
SEARCH_DEEP	false	Enables deep content search; ripgrep is used when SEARCH_RIPGREP is true.
SEARCH_RIPGREP	true	Prefer ripgrep for fast searches; fallback search is used when unavailable.
SEARCH_MAX_FILESIZE	5M	Skip files larger than this when searching their contents. Accepts 5MB, 5M, 5mb or a plain byte count.
SEARCH_TIMEOUT_MS	5000	How long one search may spend looking before answering with what it has. Reading a large tree to be certain there is nothing more is worse than an answer that arrives; the response is marked truncated when this ended it.
SEARCH_INDEX	false	Keep a full-text index of the volume's documents instead of reading them on every search. Built by a paced background pass that skips anything it has already read, and stops when the server is asked to. Results are as fresh as the last pass; searches outside the volume root — personal folders, assigned volumes — go on reading as they go.
SEARCH_INDEX_BATCH	25	Documents written per transaction while indexing.
SEARCH_INDEX_CPU_PERCENT	25	The share of one core a background pass may take. It works for a slice of time and then stands aside for the rest, so the load is what you chose whatever the files are. Raising it shortens the first pass and is felt while it runs.
SEARCH_INDEX_EXCLUDE	(none)	Folders search leaves alone, comma or newline separated, relative to the volume root. Neither the index nor a filename search walks into them — the exception being when one of them is the folder the search was started from, since navigating into it is asking to look. A build tree, a mail spool, a machine backup — hundreds of thousands of files nobody searches by content, and reading them is the whole overhead. Set here they cannot be removed from the interface; Settings → Search index holds a second list an administrator can edit. Nothing is excluded by default: with the index answering in place of the live scan, a folder left out is one that cannot be found by content.
SEARCH_INDEX_REBUILD	false	Empty the index at startup and read everything again. It is derived data — every row was read from a file that is still there — so the only cost of being wrong about needing this is one pass. Unset it once the rebuild has finished, or it happens on every start.
SEARCH_INDEX_MEMORY_MB	256	What a background pass may add to the process before it stops and carries on a couple of minutes later. Only consulted when the container enforces no memory limit of its own — where it does, three quarters of that limit is the ceiling instead. What the pass wrote is kept either way, so the next one resumes from there.
SEARCH_INDEX_RECONCILE_MS	3600000	How often to walk the volume again, for changes made outside the application — an rsync, a network share.
SHOW_VOLUME_USAGE	false	Show volume usage badges in the sidebar.
FAVORITES_DEFAULT_ICON	outline:StarIcon	Icon a new favorite starts with, as variant:IconName (outline or solid, and any Heroicons name). Each favorite can be given its own icon afterwards from the sidebar's edit mode.
USER_DIR_ENABLED	false	When true, enables a personal “My Files” space for each authenticated user under USER_ROOT. The frontend shows a “My Files” entry when this flag is on.
USER_VOLUMES	false	When true, non-admin users only see volumes assigned to them by an admin. See User volumes.
SKIP_HOME	false	When true, visits to the home view (/browse/) automatically redirect into the first volume instead.
TERMINAL_ENABLED	true	Controls the admin terminal feature. When false, terminal routes/UI are disabled. When true, nextExplorer attempts to load terminal dependencies and automatically hides/disables terminal if dependencies are unavailable (startup continues).
TERMINAL_FILE_EXTENSIONS	sh	Comma-separated list of file extensions that show the context-menu action to open the file in the admin terminal (for example sh,bash or .sh,.bash).

The sharing system (toolbar Share button, guest links such as /share/:token, and the Shared with me page) works out of the box with the feature flags above. Advanced share tuning knobs are documented under Sharing (advanced) below.

Editor

Variable	Default	Description
EDITOR_EXTENSIONS	empty	Comma-separated list of additional file extensions to support in the inline text editor (e.g., toml,proto,graphql or .toml,.proto). These are added to the built-in defaults (txt, md, json, js, ts, py, etc.), not replacing them. Changes take effect on container restart—no frontend rebuild required.
EDITOR_MAX_FILESIZE	2M	Maximum file size allowed to open in the inline text editor. Accepts a byte count or a size with K, M, G, T suffix (base 1024), e.g. 512K, 2M, 1G. Files larger than this will show “This file is too large to open in the text editor.”
PREVIEW_MAX_RENDER_SIZE	16M	How much of a document the preview will render. It renders in batches sized from what the last one cost, handing the browser back between them, so a large document appears immediately and fills in behind rather than freezing the tab; chunks off screen are skipped for layout and paint while staying findable, so Ctrl+F still crosses the whole document. What remains is the weight of the page in the tab, which is why there is still a limit. The preview reads through the editor's endpoint, so EDITOR_MAX_FILESIZE already caps what can reach it — this only bites when set lower than that.

Archives

Variable	Default	Description
ARCHIVE_EXTENSIONS	7z,zip,iso,rar,tar,gz,tgz,bz2,tbz2,xz,txz,cab,wim,cpio,rpm,deb,z,lzh,arj,zst	Extensions offered for the “Extract archive” action. A plain list (e.g. zip,iso,7z) replaces the defaults; prefix the list with + (e.g. +udf,squashfs) to extend them instead. Whatever the list says, a format is only offered when the bundled 7-Zip build actually supports it (probed at startup). Password-protected ZIP, 7z and RAR archives are supported through the extraction dialog; passwords are not persisted.

OnlyOffice & thumbnails

Variable	Default	Description
ONLYOFFICE_URL	none	Public URL for Document Server (must reach your app's PUBLIC_URL).
ONLYOFFICE_SECRET	none	JWT secret shared with OnlyOffice Document Server for /api/onlyoffice calls.
ONLYOFFICE_DOWNLOAD_ORIGINS	none	Comma-separated extra origins the Document Server may serve saved documents from. Set it when the callback URL host differs from ONLYOFFICE_URL; that origin is always allowed.
ONLYOFFICE_LANG	en	Language code for the editor UI.
ONLYOFFICE_FORCE_SAVE	false	When true, the OnlyOffice Save button writes the current version immediately.
ONLYOFFICE_AUTO_SAVE_INTERVAL_MS	30000	Minimum delay in milliseconds between background force-saves after OnlyOffice has synchronized changes. Set 0 to save only when closing; capped at 300000.
ONLYOFFICE_FORCE_SAVE_TIMEOUT_MS	10000	Retry window in milliseconds when a force-save reaches Document Server before its final changes. Minimum 7000; the interface does not wait for the callback.
ONLYOFFICE_FILE_EXTENSIONS	default list	Extra file extensions to surface to the Document Server.
FFMPEG_PATH, FFPROBE_PATH	bundled binaries	Point to custom ffmpeg/ffprobe if the bundle doesn't suit your needs.
FFMPEG_HWACCEL	none	Optional ffmpeg -hwaccel value used for video thumbnail generation when supported by your ffmpeg build (e.g. vaapi, qsv, cuda).
FFMPEG_HWACCEL_DEVICE	none	Optional ffmpeg -hwaccel_device value used with FFMPEG_HWACCEL (e.g. 0 or /dev/dri/renderD128).
FFMPEG_HWACCEL_OUTPUT_FORMAT	none	Optional ffmpeg -hwaccel_output_format value, used with FFMPEG_HWACCEL. Some hardware pipelines need it (for example vaapi) to hand frames back in a format the encoder accepts.
THUMBNAILS_ENABLED	true	Set to false to disable thumbnail generation globally, regardless of the UI setting.
THUMBNAIL_CACHE_MAX_FILES	3000	Maximum number of files kept in the thumbnail cache. Set 0 to disable automatic cleanup.
THUMBNAIL_CACHE_CLEANUP_INTERVAL_MS	3600000	Minimum delay between thumbnail cache cleanup scans.
THUMBNAIL_CACHE_CLEANUP_BATCH_SIZE	500	Maximum number of thumbnail cache files deleted per cleanup pass.
THUMBNAIL_CACHE_TTL_DAYS	30	Remove cache entries older than this age during the periodic cleanup. Set 0 to keep entries until the file-count limit is reached.
THUMBNAIL_SHARP_CACHE_MEMORY_MB	0	Memory in MB allowed for Sharp/libvips thumbnail cache. Keep 0 to minimize idle RSS after thumbnail generation.
THUMBNAIL_VIDEO_CONCURRENCY	1	Maximum number of concurrent ffmpeg thumbnail jobs. Keep low on small hosts to avoid memory spikes.
THUMBNAIL_DIAGNOSTICS_ENABLED	false	Enable periodic thumbnail diagnostics logs with queue, memory, active job, external process, and cache cleanup counters.
THUMBNAIL_DIAGNOSTICS_INTERVAL_MS	30000	Interval between thumbnail diagnostics logs when diagnostics are enabled.
THUMBNAIL_BACKGROUND_QUEUE_LIMIT	200	Maximum thumbnails queued for background generation before new requests are dropped.
THUMBNAIL_PROCESS_NICE	10	nice value applied to external thumbnail processes, so they yield to interactive work.
THUMBNAIL_VIDEO_SEEK_PERCENT	10	Position in the video, as a percentage of its duration, used to grab the thumbnail frame.
THUMBNAIL_VIDEO_SCALE_FLAGS	fast_bilinear	ffmpeg scaling algorithm for video thumbnails. Slower flags give a sharper image.
THUMBNAIL_VIDEO_SEEK_SECONDS	5	Fixed position in the video used to grab the thumbnail frame, when no percentage is set.
THUMBNAIL_VIDEO_THREADS	2	Threads allowed to one ffmpeg thumbnail job.
THUMBNAIL_SLOW_JOB_MS	10000	Duration threshold after which a thumbnail job/process is logged even when diagnostics are disabled.

Collabora (WOPI)

Variable	Default	Description
COLLABORA_URL	none	Public base URL of your Collabora CODE server (used to build the iframe URL).
COLLABORA_DISCOVERY_URL	derived	Override for discovery. Defaults to ${COLLABORA_URL}/hosting/discovery.
COLLABORA_SECRET	none	JWT secret used to sign WOPI access_token values for /api/collabora/wopi/*.
COLLABORA_LANG	en	Language code for the Collabora UI.
COLLABORA_FILE_EXTENSIONS	empty	Comma-separated list of extensions to expose (e.g. doc,docx,xls,xlsx,ppt,pptx).

Container user mapping

Variable	Description
PUID, PGID	Map container processes to host user/group IDs so created files have consistent ownership. Defaults to 1000. The entrypoint adjusts ownership of /app, /config, and /cache accordingly.