System Settings
This page covers every group under Admin -> System Settings
System settings are site-wide rules maintained directly by administrators in the admin console. Jump to the group you care about; you do not need to read from the beginning. Most changes do not require a service restart. After saving, they affect later new requests, new uploads, and newly sent emails.
Entry point:
Admin -> System SettingsStart from Your Goal
| Goal | Check This Group First | If It Is Still Wrong |
|---|---|---|
| Site links, share links, or mail link domains are wrong | Site Configuration | Then check reverse proxy |
| Login cookie, token, activation link, or email-code MFA timing is unsuitable | Authentication and Cookies | Then check login and sessions |
| Registration, Passkey sign-in, local email allow/block lists, avatars, or Gravatar behavior is unexpected | User Management | Then check login and sessions |
| Passkey, MFA, external login, or external identity binding is unexpected | Site Configuration / Admin -> External Authentication / Authentication and Cookies | Then check login and sessions |
| Mail cannot be received, or links are wrong | Mail Delivery | Then check mail |
| Browser blocks cross-origin API calls | Network Access | First confirm it is not a Public Site URL issue |
| Background tasks, thumbnails, image preview, archive preview, or trash retention behaves abnormally | Runtime / File Processing / Storage and Retention | Then check operations CLI |
| Link import file size, speed, concurrency, or timeout is unsuitable | Runtime / File Processing | Then check operations CLI |
| Audio/video playback links on share pages expire too quickly or too slowly | Runtime | Then check sharing and public access |
| WebDAV global switch, system-file blocking, or connection behavior is abnormal | WebDAV | Then check WebDAV |
| You need to see who changed what, or want to narrow the audit scope | Audit Logs | Then check admin console |
Places Administrators Change Most Often
| What you want to do | Where to change it |
|---|---|
| Make share links, mail links, WebDAV addresses, and online previews point to the correct domain | Site Configuration -> Public Site URL |
| Change the title, logo, or favicon shown on login and share pages | Site Configuration |
| Add external preview or WOPI opening methods for Office files | Site Configuration -> Preview Apps |
| Enable or limit read-only archive preview | File Processing -> Archive Preview |
| Connect OIDC / Generic OAuth2 / GitHub / QQ / Google / Microsoft login providers | Admin -> External Authentication |
| Disable public registration | User Management -> Allow Public User Registration |
| Temporarily disable Passkey sign-in | User Management -> Registration & Login -> Allow Passkey Sign-In |
| Restrict email addresses usable for local registration and local email changes | User Management -> Registration & Login -> Local Account Email Allowlist / Blocklist |
| Change the default quota for new users; teams created without an explicit quota also use it, so recheck actual team quotas after creation | Storage and Retention -> New User Default Storage Quota |
| Tune cookie security requirements and Access / Refresh Token TTLs | Authentication and Cookies |
| Tune activation, email-change, and password reset link TTLs | Authentication and Cookies |
| Enable email-code MFA, or allow TOTP users to use email codes as fallback | Authentication and Cookies |
| Tune the external login email verification mail template | Mail Delivery -> External Login Email Verification |
| Tune the login email code mail template | Mail Delivery -> Login Email Code |
| Configure SMTP, send test mail, or edit transactional mail templates | Mail Delivery |
| Tune retention for trash, version history, and team archives | Storage and Retention |
| Tune temporary background task artifact retention | Runtime -> Background Tasks |
| Tune the online extraction staging size limit | File Processing -> Online Extraction Staging Size Limit |
| Tune thumbnail size limits, image preview strategy, and vips / ffmpeg / ffprobe processors | File Processing -> Media Processing |
| Tune HTTP/HTTPS link import file size, speed, concurrency, and timeout | File Processing -> Link Import |
Disable WebDAV, or adjust blocking for system files such as .DS_Store and Thumbs.db | WebDAV |
| Tune mail dispatch, background task dispatch, concurrency, retry, and periodic cleanup frequency | Runtime |
| Tune the temporary audio/video streaming session TTL on share pages | Runtime -> Share Streaming Playback Session TTL |
| Enable or disable audit logs, or adjust the recorded scope | Audit Logs |
Current Groups
- Site Configuration - Public site URL, title, logo, favicon, preview apps
- User Management - Public registration, registration activation, Passkey sign-in, local email allow/block lists, avatars, Gravatar
- Authentication and Cookies - Cookie security rules, token TTLs, activation/email-change/reset link TTLs, email-code MFA
- Mail Delivery - SMTP, sender, test mail, registration activation/email-change/password reset/external login email verification/login email code mail templates
- Network Access - Browser cross-site access rules (CORS)
- Runtime - Mail queue, background tasks, temporary task artifact retention, task-lane concurrency, share streaming playback sessions, periodic cleanup, low-level consistency checks, follower node health checks, list limits
- Storage and Retention - Trash, version history, default quotas
- File Processing - Online extraction, archive building, archive preview, link import, thumbnails, media metadata, and media processors
- WebDAV - Global switch and common system-file blocking
- Audit Logs - Switch, recorded scope, and retention time
- Custom Configuration, Other - Advanced scenarios only
Site Configuration
If the site needs to be accessed externally, configure this group first.
Public Site URLEnter the HTTP(S) origins users actually use to access the site. Fill one origin per input in the list, for example:texthttps://drive.example.com https://panel.example.comEach item should contain only the origin: protocol, domain, and optional port. Do not include paths, do not include
/api, and do not use wildcards. The system uses these origins to generate share pages, mail links, WebDAV addresses, Office / WOPI preview URLs, and absolute URLs needed by later callbacks. When left empty, most browser pages can work from the current access address, but external entry points are more likely to generate wrong links. Production deployments should explicitly configure the public site URL.If the same instance is accessed through multiple domains, add all of them to this list. AsterDrive finds an exact matching origin in the list based on the current request Host. If matched, it uses that origin to generate links. If not matched, it uses the first item as the fallback origin.
This is not a CORS allowlist
Public Site URLmeans "which public entry points belong to this AsterDrive instance", and it also participates in same-site CSRF trust decisions for cookie writes. It does not automatically allow browsers to call APIs cross-origin. Cross-origin access is configured separately underNetwork Access -> Allowed CORS Origins.Site Title,Site DescriptionAffect the title and description on login pages, share pages, and app pages.favicon, light logo, dark logo Affect branding shown in browser tabs, login pages, and the site header.Preview AppsProvide additional "open with" options for Office, PDF, spreadsheet, or other files. Built-in previewers, external URL templates, and WOPI opening methods are managed here together.WOPI-related TTLsAdjust these only when integrating online Office preview/editing services such as OnlyOffice. Normal deployments should keep the defaults.
Recommended order for enabling WOPI
- Configure
Public Site URLcorrectly first - Enable an existing app under
Preview Apps, or import a new app throughWOPI Discovery - Confirm the external Office / WOPI service can call back to
/api/v1/wopi/...generated fromPublic Site URL - If browser cross-origin calls to the AsterDrive API are blocked, allow the corresponding origin under
Network Access - Open real
docx/xlsx/pptxfiles once and confirm they can be saved back to AsterDrive
WOPI access token TTL, WOPI lock TTL, and WOPI discovery cache duration are all in this group. Adjust them manually only after you have connected a WOPI service and actually run into problems such as session expiry or discovery updates not taking effect in time.
User Management
This group controls account entry points and avatar-related behavior.
Allow Public User Registration- After disabling it, the login page only supports existing-account login and administrator initialization. New accounts can only be created by administrators.Require Email Activation After Registration- After enabling it, normal users created through public registration must click the activation email before logging in.Allow Passkey Sign-In- After disabling it, users cannot sign in with registered Passkeys. Existing Passkeys are not deleted and can be used again after re-enabling the setting.Local Account Email Allowlist- Restricts email addresses or exact domains allowed for local registration and local email changes. Empty means no allowlist restriction.Local Account Email Blocklist- Blocks email addresses or exact domains for local registration and local email changes. The blocklist overrides the allowlist.Avatar Directory- User-uploaded avatars are written to this local directory. Relative paths resolve under server-side./data.Avatar Upload Size Limit- Avatar files exceeding this limit are rejected directly.Gravatar Base URL- If official Gravatar access is unstable, change it to a proxy or mirror.
The local email allowlist / blocklist applies only to local-account flows, not third-party SSO. Entries can be alice@example.com, example.com, or @example.com; domain entries are exact matches, so example.com does not automatically match sub.example.com. Internationalized domains must use punycode.
Authentication and Cookies
This group decides browser login behavior and session safety.
Authentication Cookie Sent Only Over HTTPS- Keep enabled in production. Disable temporarily only for local or intranet plain-HTTP trial runs.Access Token TTL,Refresh Token TTL- Control how long login state is maintained.Registration Activation Link TTLEmail Address Change Link TTLPassword Reset Link TTLVerification Email Resend CooldownPassword Reset Request CooldownRequire Email Code MFA- Requires working mail delivery. After enabling it, verified-email users without TOTP can complete second-factor verification with an 8-digit email code after password or external identity login.Allow TOTP Email Fallback- Allows users who already have an authenticator to choose email code on the MFA login page. Security-sensitive sites can keep it disabled.Email Login Code TTL- Default is10minutes; actual validity never exceeds the remaining lifetime of the current MFA login flow.Email Login Code Resend Cooldown- Default is60seconds.
For normal deployments, you usually only need to confirm cookie security requirements and link TTLs match your site policy.
Email codes depend on mail security
Email-code MFA is useful only when SMTP delivery is reliable and user email addresses are verified. Before enabling it, send a test mail under Mail Delivery and confirm the Login Email Code template matches your site's wording.
Mail Delivery
This group decides whether registration activation, password reset, and email address change emails can be sent. The most commonly changed items are:
- SMTP host, port, username, password
- Sender address and sender name
- Whether to enable SMTP encryption
- Test mail
- Registration activation, password reset, email address change, external login email verification, and login email code mail templates
Check before enabling registration
If the site will allow registration, password recovery, or email address changes, check mail configuration and Public Site URL together. Do not configure only one of them.
If external authentication allows users to continue binding or account creation through email verification, it also depends on this mail configuration group.
See mail for detailed guidance.
Network Access
This group mainly handles browser cross-site access rules (CORS).
Change it only in these scenarios:
- The browser page and AsterDrive are not under the same domain
- You want another site to call AsterDrive directly from the browser
Same-site deployments usually do not need changes
Most deployments where "frontend pages and APIs are on the same site" do not need to touch this group.
When connecting an external WOPI service, the most common issue is not here. It is usually that the Office service cannot call back to the WOPI URL generated from Public Site URL. Add an origin here only when the browser console clearly reports a CORS error for the AsterDrive API.
Runtime
Administrators decide the pace of background work here. Default behavior:
| Task | Default Frequency |
|---|---|
| Mail queue scan | Every 5 seconds |
| Background task queue scan | Every 5 seconds |
| Background task idle backoff maximum | Every 60 seconds |
| Periodic cleanup | Every 1 hour |
| Low-level file consistency check | Every 6 hours |
| System health checks (database / cache / follower nodes) | Every 5 minutes |
You can also tune:
- Background task idle backoff maximum
- Temporary background task artifact retention
- Reserved fallback background task concurrency limit. It is currently used only by future unclassified task kinds, not by existing task lanes
- Concurrency limit for archive tasks: online compression, online extraction, and archive preview
- Thumbnail generation task concurrency limit
- Storage policy migration task concurrency limit
- Maximum background task attempts
- Share download rollback queue capacity
- Share streaming playback session TTL
- System health check interval
- Team member list page size limit
- Task list page size limit
If there are no obvious performance issues, queue backlogs, or follower node detection delays, keep the defaults.
If you increase concurrency for the archive, thumbnail, or storage-migration lanes, matching tasks can run together more easily, and CPU, memory, network, and I/O pressure will increase with them. The reserved fallback concurrency cap is not a "global total concurrency" setting, so do not rely on it to limit every background task.
Task retention controls how long temporary background task artifacts are kept, defaulting to 24 hours. It mainly affects temporary files or downloadable results produced by package downloads, online compression, online extraction, and link-import tasks. Task records themselves remain as history in the task list until an administrator conditionally cleans finished records.
Audio and video on share pages create a short-lived streaming playback session first to support Range playback. The default TTL is 3 hours, configurable from 5 minutes to 24 hours. Longer TTLs work better for long background music playback; shorter TTLs reduce the access window after a link leak.
Storage and Retention
This group decides "how long data is kept" and "how much space new users / new teams get by default". Default rules:
| Item | Default |
|---|---|
| Historical versions per file | 10 |
| Trash retention | 7 days |
| Team archive retention | 7 days |
| New user default storage quota | 0 (unlimited) |
Default quotas affect only accounts and teams created later
- The UI label for this item is
New User Default Storage Quota - When an administrator creates a team without entering an explicit quota, the team also uses this default value
- After creating a team, recheck the actual team quota under
Admin -> Teams - This setting only affects accounts and teams created later. Existing accounts or teams are not automatically rewritten.
File Processing
This group controls features that read, scan, transform, or temporarily unpack file contents. Default rules:
| Item | Default |
|---|---|
| Online extraction source archive size limit | 512 MiB |
| Online extraction staging size limit | 2 GiB |
| Online extraction uncompressed size limit | 1 GiB |
| Online extraction entry count limit | 10000 |
| Online extraction duration limit | 300 seconds |
| Online archive compression global switch | Enabled |
| Archive build entry count limit | 10000 |
| Archive build total source size limit | 2 GiB |
| Archive build output size limit | 2 GiB |
| Archive preview global switch | Disabled |
| Archive preview user-side switch | Disabled |
| Archive preview share-side switch | Disabled |
| Archive preview source file size limit | 64 MiB |
| Archive preview entry count limit | 2000 |
| Archive preview manifest size limit | 64 KiB |
| Archive preview scan duration limit | 30 seconds |
| Link import engine registry | builtin enabled, aria2 disabled |
| Link import file size limit | 1 GiB |
| Link import download speed limit | 5 MB/s (0 still means unlimited) |
| Link import concurrency limit | 1 |
| Link import request timeout | 600 seconds |
| aria2 RPC request timeout | 10 seconds |
| aria2 split | 5 |
| aria2 per-server connections | 5 |
| aria2 low-speed limit | 0 (disabled) |
| Thumbnail source file size limit | 64 MiB |
| Image preview strategy | Original first |
| Media metadata extraction | Enabled |
| Media metadata source file size limit | 256 MiB |
Archive Preview
Archive preview is read-only. It scans metadata from supported archive formats and generates a manifest; it does not extract the archive into the user's folder. It is not the same thing as "online extraction".
This group has three layers of switches:
- Enable Archive Preview: global switch
- Enable Archive Preview for Users: whether logged-in users can preview archives in personal and team spaces
- Enable Archive Preview for Shares: whether public share pages can preview archives after passing password and share-scope checks
All three are disabled by default. Enable them only when users really need to inspect archive contents, especially the share-side switch. It lets visitors see metadata such as internal file names, directory structure, sizes, and modified times.
Limits control source archive size, entry count, returned manifest size, and single-scan duration. When an archive is opened for the first time and the manifest has not been cached, the system creates an archive_preview_generate background task. After generation completes, reopening reuses the cached manifest.
When users switch filename encoding in the preview toolbar, AsterDrive rereads or regenerates the manifest with the selected encoding. This is for old ZIP files or ZIP file names created across language environments that display as garbled text. It does not modify the original archive.
Online Extraction and Archive Building
Online extraction, online compression, and folder archive download all use the archive background-task lane, and all of them use the server temporary directory. The defaults are sized for common personal and small-team files. Do not raise every limit immediately.
Enable online archive compression only controls whether users can create a new ZIP archive from selected files and folders. It is enabled by default. When disabled, new online-compression tasks are rejected. Online extraction, folder archive downloads, and archive preview are controlled by their own settings and are not disabled by this switch.
If users often process large archives or large folders, check these settings separately:
- Online extraction source archive size limit: rejects source archives that are too large
- Online extraction staging size limit: counts the source archive downloaded locally plus files extracted into staging
- Online extraction uncompressed size, entry count, path depth, compression ratio, and duration limits: protect against archive bombs and abnormal metadata-heavy archives
- Archive build entry count, total source size, and output size limits: affect batch online compression and folder archive downloads
Before raising these limits, confirm that the disk backing server.temp_dir, CPU, and archive-task concurrency can handle the extra load. Otherwise the usual result is not "larger files work", but "tasks queue longer or the temp disk fills faster".
Link Import
Link import creates a dedicated background-task lane that lets the server download a file from an HTTP/HTTPS source and import it into the current workspace. These runtime settings only control size, speed, concurrency, timeout, and the selected builtin / aria2 download engines.
Defaults are chosen to be usable without enabling unlimited outbound bandwidth: builtin enabled, aria2 disabled, file size limit 1 GiB, speed limit 5 MB/s, concurrency 1, and request timeout 600 seconds. aria2-specific values apply only after the aria2 engine is enabled.
For full behavior, security boundaries, aria2 deployment, and troubleshooting, see Offline Download.
Media Processing
Media processing is responsible for backend generation of thumbnails, image previews, and media metadata. It now has a structured editor under File Processing -> Media Processing, so you do not need to edit JSON manually.
You can do these things there:
- Enable or disable a processor
- Bind file extensions to a processor
- Configure commands used by
vips_cli,ffmpeg_cli, orffprobe_cli - Test whether the command can be executed by the server
- Keep AsterDrive's built-in image processor as a fallback
- Configure the generated thumbnail and image-preview maximum dimensions
- Choose whether the web image preview dialog loads the original file first or the generated medium preview first
The default built-in path covers common image formats.
If you want to extend support for HEIC, AVIF, PDF covers, video thumbnails, or video metadata, you can connect vips, ffmpeg, or ffprobe, but only if those commands are actually installed in the server environment.
Thumbnail max dimension and Image preview max dimension control generated derivative size, not source-file eligibility:
thumbnail_max_dimensionlimits generated thumbnail width and height. The default is400pixels.image_preview_max_dimensionlimits generated image-preview width and height. The default is1600pixels.- Both settings are maximum-edge limits: generated derivatives keep aspect ratio, and
max(width, height)is kept at or below the configured value. - The same dimensions are passed to storage-native thumbnail providers through
NativeThumbnailRequest.max_widthandmax_height.
Changing either value does not rewrite existing derivatives in place. New cache paths and ETags include the non-default dimension in the derivative version namespace, such as 1-d320 or 1-d2048, so clients and storage backends do not accidentally reuse a derivative generated at another size. If you switch back to the default value, AsterDrive uses the default derivative version namespace again.
Image preview strategy only changes which image source the web preview dialog loads by default:
- Original first: when the browser can render the current format, load the original file first; if the browser cannot render it or the original fails, use the backend-generated preview.
- Medium preview first: load the backend-generated WebP preview first, and download the original only when the user chooses to view it.
If users often open large photos, or object-storage egress bandwidth is sensitive, choose "Medium preview first". This setting does not change original files and does not affect thumbnail caches; it only changes the frontend preview dialog's default loading order.
Keep the built-in processor first
Unless you have confirmed the command paths, permissions, and extension bindings for vips / ffmpeg / ffprobe, keeping the built-in processor as a fallback is simpler.
Media processing ENV on first startup
When the service initializes system settings for the first time, it reads three bootstrap environment variables to decide whether CLI processors are enabled in the default media processing configuration:
ASTER_BOOTSTRAP_ENABLE_VIPS_CLI=true
ASTER_BOOTSTRAP_ENABLE_FFMPEG_CLI=true
ASTER_BOOTSTRAP_ENABLE_FFPROBE_CLI=trueThe official Docker image already installs vips, ffmpeg, and ffprobe, and enables these three bootstrap ENV values by default. New databases usually get the corresponding processors directly.
These three variables only affect the initial default value when media_processing_registry_json does not yet exist. This rule table is the unified media processing configuration entry point. It manages enabled state, capability purposes, extension bindings, and command paths for built-in images, built-in lofty, VIPS CLI, FFmpeg CLI, and FFprobe CLI. Thumbnails and media metadata both use this path.
Media Metadata
Media metadata and thumbnails share media_processing_registry_json:
media_metadata_enabledis the global switchmedia_metadata_max_source_byteslimits the source file size accepted by media metadata background tasks- When the
imagesprocessor is enabled and has themetadata:imagepurpose, it handles image metadata - When the
loftyprocessor is enabled and has themetadata:audiopurpose, it handles audio metadata; when it has thethumbnail:audiopurpose, it generates WebP thumbnails from embedded audio covers - When the
ffprobe_cliprocessor is enabled and has themetadata:videopurpose, it handles video metadata; itsconfig.commandcan be a command name or an absolute path
If server-side ffprobe has been renamed, is not in PATH, or needs a custom installation path, change ffprobe_cli.config.command in media_processing_registry_json to the corresponding command or absolute path, then run test_ffprobe_cli in the media processing registry to probe it.
WebDAV
This group controls site-wide WebDAV runtime behavior:
Enable WebDAVBlock WebDAV System FilesBlocked WebDAV System-File Patterns
After disabling it, desktop clients can no longer access files through WebDAV immediately.
By default, AsterDrive blocks WebDAV clients from creating common operating-system metadata files and folders, including .DS_Store, ._*, .Spotlight-V100, .Trashes, .fseventsd, Thumbs.db, desktop.ini, $RECYCLE.BIN, and System Volume Information. These are usually written automatically by Finder, Windows Explorer, or sync tools, and most deployments do not want them scattered through the drive.
The patterns match basenames, ignore case, and support simple * wildcards. Disable this behavior or remove a pattern only when you explicitly need to sync those system files.
Change the path prefix in the site configuration page
If you only want to change the WebDAV path prefix or the hard WebDAV upload size limit, that is not on this page. Change [webdav] in config.toml instead, then restart.
Audit Logs
This group decides whether admin and key operations leave records, and also lets you narrow the recorded action scope.
Enable Audit LogsRecorded Audit ActionsAudit Log Retention
Do not disable casually
If you want to later investigate "who deleted files, who created shares, who changed team members", keep it enabled.
The primary node's service startup and shutdown are also recorded as audit events, as server_start and server_shutdown.
When Changes Take Effect
| Change | Effective Timing |
|---|---|
| Site address, title, logo, favicon | Shown with the new values after refreshing the page |
| Preview apps / online Office related settings | Applied to previews opened later |
| WOPI access token / lock / discovery cache | Applied to new WOPI sessions opened later |
| Public registration, registration activation, mail templates | Applied to later login flows and newly sent emails |
| Local email allowlist / blocklist | Applied to later local registration and local email changes; third-party SSO is not affected |
| Passkey sign-in switch | Applied to later Passkey sign-in requests; existing Passkeys are not deleted |
| External login providers | Applied to the login page and later external login flows after saving |
| External login email verification mail template, login email code mail template | Applied to newly sent matching emails |
| Email-code MFA switch, fallback policy, TTL, and resend cooldown | Applied to later MFA login flows and newly sent email codes |
| Cookie security, token TTLs | Applied to later login, refresh, and share password verification |
| Avatar directory, avatar size limit | Applied to avatar uploads after the change |
| Default quota | Only affects accounts created later, and teams created later without an explicit quota |
| Audit log switch and recorded scope | Later audit writes follow the new scope |
| Audit log retention window | Background cleanup tasks work with the new rules |
| Version history limit | Applied when new versions are produced later |
| Online extraction staging limit | Applied to online extraction tasks created later |
| Online extraction source, uncompressed size, entry count, path depth, compression ratio, and duration limits | Applied to online extraction tasks created later |
| Online archive compression global switch | Applied to online-compression tasks created later; does not affect online extraction, folder archive downloads, or archive preview |
| Archive build entry, total source size, and output size limits | Applied to online compression and archive download tasks created later |
| Link import engine registry, temp directory, file size, speed, concurrency, request timeout, and aria2 parameters | Applied to link-import tasks created later; manual retries clean old artifacts from both the default temp directory and the current offline-download temp directory |
| Archive preview switches and limits | Applied to later requests and new archive_preview_generate tasks |
| Thumbnail source file size limit | Applied to files entering thumbnail and image-preview tasks later |
| Thumbnail and image-preview max dimensions | Applied to later thumbnail and image-preview generation; non-default dimensions use dimension-specific cache paths and ETags |
| Image preview strategy | Applied when the frontend later opens image previews and chooses the default source |
| Media processor switches, commands, extension bindings | Applied to files entering thumbnail and image-preview tasks later |
| Media metadata switch, size limit, processor binding | Applied to files entering media metadata tasks later; existing caches are not automatically rescanned because configuration changed |
| Mail dispatch, background tasks, periodic cleanup, follower node health check frequency | Applied to later background polling |
| Background task lane concurrency and maximum attempts | Applied to background tasks scheduled or retried later |
| Share streaming playback session TTL | Applied to audio/video playback sessions created later on share pages |
| WebDAV switch, system-file blocking rules, CORS | New requests respond with the new rules immediately |
About "Custom Configuration"
The Custom Configuration group is mainly for custom frontend developers. It is a global-variable persistence layer reserved for custom frontend developers.
If you replace the frontend with your own version by using the ./frontend-override/ directory, and you need to persist some site-level configuration such as theme, brand color, custom entry points, or third-party integration credentials, you can write them into the database through Custom Configuration, then expose them to the frontend through backend APIs.
Naming convention
Custom configuration keys use the {namespace}.{name} form, for example:
my-frontend.thememy-frontend.brand.primary_colormy-frontend.feature.enable_xxx
Use an identifier for your custom frontend as namespace to avoid conflicts with others. Built-in system configuration is all source="system"; custom configuration is source="custom". The admin console separates them by this field.
Keep it empty when not using a custom frontend
For normal deployments using the official frontend, leave the whole Custom Configuration group empty. Its content does not affect any official frontend feature.
If you just want to find things like "theme color", "site title", or "Logo", adjust them in the Site Configuration group.