feat: Make core.wwwdir and core.pluginsdir user-configurable to support split storage setups

[antonkarliner]

Is your feature request related to a problem? Please describe.

When core.datadir is set to an absolute path pointing to external/network storage (e.g. a NAS share or a Home Assistant network mount), TeddyCloud becomes unable to serve the web GUI. This is because internal.wwwdirfull is always resolved as {datadirfull}/www, but in containerised deployments the www assets are baked into the container image at a fixed internal path — they are never on the external storage volume.

The split-storage use case is legitimate and common: keep large content/library files on slow external storage, while server binaries and web assets stay on fast internal storage. Currently this configuration is impossible to achieve cleanly because there is no way to point wwwdirfull at the container-internal www path independently of core.datadir.

To reproduce:

Set core.datadir to an absolute path that differs from the container-internal data directory, e.g.:

core.datadir=/mnt/nas/teddycloud
core.contentdir=/mnt/nas/teddycloud/content/default
core.librarydir=/mnt/nas/teddycloud/library

TeddyCloud will fail sanity checks or serve 404s for all web UI requests, because it looks for www assets at /mnt/nas/teddycloud/www instead of the container-internal /teddycloud/data/www.

Error in logs:

ERROR|server.c:0758:sanityCheckDir()| Config item 'internal.wwwdirfull' is set to '/mnt/nas/teddycloud/www' which was not found

Or if the directory is manually created (empty), the server starts but all web requests return 404.

Describe the solution you'd like

Promote core.wwwdir (and core.pluginsdir) from OPTION_INTERNAL_STRING to OPTION_STRING in src/settings.c, making them user-configurable via config.ini just like core.contentdir, core.librarydir, core.firmwaredir, and core.cachedir already are.

Current code (src/settings.c):

OPTION_INTERNAL_STRING("core.wwwdir", &settings->core.wwwdir, "www", "WWW dir", LEVEL_NONE)
OPTION_INTERNAL_STRING("core.pluginsdir", &settings->core.pluginsdir, "plugins", "plugins dir", LEVEL_NONE)

Proposed change:

OPTION_STRING("core.wwwdir", &settings->core.wwwdir, "www", "WWW dir", "Directory for web UI assets (relative to datadir, or absolute)", LEVEL_EXPERT)
OPTION_STRING("core.pluginsdir", &settings->core.pluginsdir, "plugins", "Plugins dir", "Directory for web plugins (relative to wwwdir, or absolute)", LEVEL_EXPERT)

This is consistent with how all other data directories are already handled, and the default value "www" preserves full backwards compatibility.

Describe alternatives you've considered

1. Setting core.datadir to / — works as a security boundary but breaks other internal path derivations and is a security concern.
2. Symlinking — not possible in containerised environments like Home Assistant OS where the container filesystem is inaccessible from the host.
3. Manually copying www assets to external storage — works as a workaround (extract from the release zip), but the www files then go stale on every TeddyCloud update and must be manually re-synced. Not viable long-term.
4. Setting core.datadir to a path that covers both locations — impossible when www lives inside the container and content lives on external storage, as no single path can be an ancestor of both.

Additional context

This affects the Home Assistant addon (mrueg/addon-teddycloud) when used with network storage, but the root cause is in the core teddycloud settings system.

The addon mounts config at /addon_configs/.../teddycloud/ (fast internal HA Green SSD) but users may want content/library on a network share at /share/teddycloud/teddycloud/. With the current design, pointing core.datadir at the share breaks www; leaving it at data means the path security check in handler_cloud.c (osStrncmp(tonieInfo->contentPath, client_ctx->settings->internal.datadirfull, dataPathLen)) blocks serving any content from the share.

Technical details:

• Version: tc_v0.6.7 (5b59a82-dirty)
• Home Assistant OS 17.1 (aarch64 / green)
• HA Add-on version: 0.5.4
• Home Assistant Core: 2026.2.2

[SciLor]

Thank you for your very detailed Feature Request.

For now, following workarounds can be offered, that you already mentioned, not working for your ENV:

• For normal Docker Containers, you may set the volumes as mounts to a specific path
• Use a symbolic link to the directory you need.

Are you sure this change will fix the problem? It may be the case that then the www dir isn't in data anymore and this will serve 404s again.

[antonkarliner]

@SciLor
Spent half of the Sunday trying to debug :)

Speaking of workarounds: in the Home Assistant addon environment, volume mounts are defined by the addon itself and can't be changed by the user, and symlinks require access to the container filesystem which HA OS doesn't expose.

As for 404, the path security check (osStrncmp against internal.datadirfull in handler_cloud.c:handleCloudContent()) only applies to TAF files served to the Toniebox. The web UI is served by a separate static file handler that simply looks up files relative to internal.wwwdirfull with no security boundary check. So pointing core.wwwdir at a path outside of datadirfull won't cause any rejections, I tried this during debugging: when pointed datadirfull at external storage and manually created an empty www directory there, TeddyCloud started and passed the sanity check fine, but returned 404s purely because the directory was empty, not due to any security check.

The idea is that core.wwwdir becomes independently configurable just like core.contentdir and core.librarydir already are, enabling a split-storage config like this:
core.datadir=/share/teddycloud # external — security boundary for content serving
core.contentdir=/share/teddycloud/content/default # external — large files
core.librarydir=/share/teddycloud/library # external — large files
core.wwwdir=/teddycloud/data/www # container-internal — already baked into the image

The www assets are small, static, and already inside the container image — there's no reason to put them on external storage. This change just allows the two to be decoupled.

[SciLor]

Feel free to create an PR for that then.
Thank you for going thaaaat deep.

[henryk86]

Won’t that be a breaking change if you have already plugins stored in that path?

[henryk86]

Or also mapped the custom_img folder in the www directory

[antonkarliner]

@henryk86 good point, but it's not a breaking change because the default value remains "www", which resolves identically to the current hardcoded behaviour. Users who don't set core.wwwdir in their config get exactly the same paths as today.
For plugins and custom_img: since those are subdirectories of wwwdir, they follow it automatically. A user pointing core.wwwdir=/teddycloud/data/www would still have plugins at /teddycloud/data/www/plugins and custom images at /teddycloud/data/www/custom_img — unchanged.