feat(synology): native DSM package with standalone server and DSM SSO

[erseco]

Summary

Replace the Synology container wrapper with a native DSM 7.2+ x86_64 package containing the eXeLearning standalone server and its required runtime assets. Users install the SPK in Package Center and open eXeLearning from DSM using their existing DSM session, without entering their password again.

Native runtime and persistence

• Compile the server with Bun embedded; no runtime Docker, Container Manager, Node.js or separate Bun installation is required.
• Run as the unprivileged package account, listening on 127.0.0.1:8085. DSM nginx exposes /exelearning/, including WebSockets and project uploads.
• Keep SQLite, project files, configuration, generated secrets and logs under SYNOPKG_PKGVAR, independently of the immutable application files.
• Preserve data during application and package-revision upgrades. Add service lifecycle checks, graceful shutdown and the DSM upgrade/uninstall hooks.
• Remove the obsolete Synology compose file and container resources. General eXeLearning Docker support remains available.

DSM authentication

The isolated package bridge obtains the current session's DSM CSRF token and supplies it only to the package CGI. Synology's server-side authenticate.cgi validates the session and determines the username; browser-supplied identities are never trusted.

Short-lived signed assertions are state-bound and replay-checked, then exchanged through the existing eXeLearning authentication/session infrastructure. Users map to stable synology:<username> identities, receive ROLE_USER, and are marked as externally authenticated. Local password management is unavailable for these accounts; administrator promotion is an explicit local operation.

Packaging and releases

make package-synology VERSION=<version> PACKAGE_REVISION=<revision> builds an architecture-specific SPK and SHA-256 checksum. The package validates its archive, runtime assets and service files, preserves the upstream SemVer, and normalizes DSM metadata versions separately.

The release workflow builds from the checked-out release tag and attaches stable, beta or RC packages to that same GitHub release. Manual runs require an existing version tag and publish workflow artifacts only. The workflow does not look up the latest upstream release.

Demo

Real DS918+ running DSM 7.2.2: manual SPK update, opening eXeLearning with the DSM session, importing an ELP file and previewing its contents. 39 seconds, 720p, approximately 560 KB, no audio. Edited capture with waits shortened; this demonstrates an upgrade of an existing installation, not a fresh install.

synology-native-demo.mp4

Validation

Check	Result
Frozen-lockfile install; normal asset and standalone build	Passed
make fix, ShellCheck, archive/checksum validation, architecture checks	Passed; existing Biome warnings remain
Unit suite	8,838 passed
Integration suite	770 passed
Frontend coverage suite	16,120 passed
Focused packaging/auth/admin/renderer suite	297 passed
Full web E2E suite	564 passed; 11 existing skips
Full static E2E suite	453 passed; 134 existing skips
Final focused web/static tests after DSM handshake changes	2 passed in each target
Focused changed executable TypeScript coverage	264/266 lines, 99.25%

The complete E2E suites ran during implementation; the final handshake changes were additionally checked with the focused browser suites and on the NAS. No tests were disabled for this change. Compilation/lifecycle wrappers are exercised through package and device checks; the coverage figure above is the focused LCOV scope, not a claim about every shell or browser-script line.

Verified on physical hardware: DS918+, Celeron J3455 (SSE4.2, no AVX2), DSM 7.2.2-72806 Update 9. Native installation/upgrades, unprivileged service, loopback binding, nginx registration, service recovery, persistent data/configuration, real DSM-session SSO, project save/reopen, ELP import, ELPX download, preview and same-account two-tab WebSocket synchronization passed. The extracted native package also passed executable/SQLite/template/static-asset smoke checks as the package account.

Remaining verification: collaboration between independent DSM users, large uploads, administrator bootstrap, application logout without DSM logout, uninstall/reinstall retention, other NAS models and actual release/prerelease artifact attachment. ARM support is not advertised. Immediately after the recorded upgrade, the first browser request reached DSM's temporary 404 page; reloading succeeded while nginx registered the route. Fresh SQLite initialization on this NAS can take several minutes during Btrfs fsync; durability settings were not weakened.

Local test artifact: exelearning-4.0.5-9-x86_64.spk (86,480,384 bytes). This was built from the development working tree, not a published upstream release.

SHA-256: 9bf8c70cd92515a28880a93b12c53a2b668ed28db4086247c4c6b9cffb0637c2

Documentation

• Deployment, configuration and troubleshooting
• ADR-41-01: native Synology packaging
• Implementation research and verification scope

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[codecov]

Bundle Report

Bundle size has no change ✅