Troubleshooting extension installation

[colons]

The instructions in the README here say:

[...] upload the specific extension(s) you want on your server. Extensions must be in the ./extensions directory of your FreshRSS installation.

If that doesn't work, what do I do? I have put an extension in the extensions folder in my FreshRSS folder:

$ tree extensions/
extensions/
├── AutoTTL
│   ├── configure.phtml
│   ├── extension.php
│   ├── metadata.json
│   [...]
├── index.html
└── README.md

Other than there being configure.phtml instead of configure.php, this mirrors what's expected according to the documentation. But the extension is not appearing in the list of extensions in FreshRSS settings. How do I troubleshoot this? I don't know if there's configuration for me to check or log files I can look at to see if extension discovery is even being attempted, let alone why it might be failing.

[salvador-castro]

Thanks for the detailed report! A few things to check, in order of likelihood:

1. Permissions: the web server process needs read+execute permission on the extensions directory and on extensions/AutoTTL itself (recursively). If permissions are missing, FreshRSS will silently fail to list anything — there's no error in the UI, only in the PHP/web server error log (look for a scandir() warning from ExtensionManager.php).

2. metadata.json: can you paste the contents? It needs to be valid JSON with at minimum name and entrypoint fields. A trailing comma or wrong quote type will cause it to be silently skipped.

3. Class name match: in extension.php, the class name must be exactly {entrypoint}Extension. If entrypoint in metadata.json is "AutoTTL", the class must be named AutoTTLExtension — a mismatch causes the extension to be ignored without any visible error.

4. configure.phtml (not .php) is correct, so that's not the issue — the admin docs page is just outdated on that point.

5. If you're on Docker, double check the extensions volume/bind mount actually points to the same extensions/ directory you're inspecting on the host — there are several reports of people editing a directory that isn't actually mounted into the container.

As a sanity check, it might help to try copying a known-good official extension (e.g. xExtension-CustomCSS from https://github.com/FreshRSS/Extensions) into the same folder — if that one also doesn't show up, it points to a permissions/path issue rather than something specific to AutoTTL.

[colons]

i guess maybe documentation should be updated to mention that, if THIRDPARTY_EXTENSIONS_PATH is set, that's where extensions should be put? it's implied both here and in the docs that ./extensions is always where you should put them, which isn't true

[salvador-castro]

Good point, and worth flagging separately. Both the README and the admin docs page (https://freshrss.github.io/FreshRSS/en/admins/15_extensions.html) state "upload to ./extensions" as if it's unconditional, with no mention that THIRDPARTY_EXTENSIONS_PATH (settable in data/constants.local.php) overrides that location. Since this is exactly the kind of thing that's invisible until you've forgotten you set it months ago, it'd be worth a one-line addition near the install instructions along the lines of: "If THIRDPARTY_EXTENSIONS_PATH is set in constants.local.php, extensions go there instead of ./extensions."

Want me to open a docs PR for this, or would you rather file it as its own issue so it doesn't get buried in a closed troubleshooting thread?

[colons]

i think you have a better handle on how to phrase such an issue, i'd appreciate it if you could do that. thanks again, i hope this helps

[salvador-castro]

No problem, happy to. I'll file a docs issue referencing this discussion so the context isn't lost. I'll drop the link here once it's up.

[salvador-castro]

FreshRSS/FreshRSS#8927