docs: add self-contained usage guide #2

Closed

forkfixer-kaki wants to merge 1 commit from forkfixer-kaki/dynapt:docs/self-contained-readme into master

forkfixer-kaki commented

2026-10-27 21:50:04 +01:00

First-time contributor

Summary

Closes #1.

This makes the repository self-contained by expanding README.md with the experimental setup guide that currently lives in a Gist. The documentation is adapted to match the current code paths and repository layout.

No functional application code is changed.

What changed

Documented the project scope, supported architectures, runtime commands, and experimental status.
Added installation instructions for the current development release and both Debian packages.
Documented configuration in /opt/dynapt/config.json, including port, concurrency, apps, and githubAccessToken.
Added APT source setup, server startup, and boot-time startup instructions.
Documented application configuration for:
- direct DEB downloads,
- direct AppImage downloads and the optional appimage.bin command link,
- GitHub releases, including repo, filter, and prerelease,
- jq filters for metadata endpoints that return a package URL,
- automatic id generation and cache behavior.
Added complete direct-download examples for Discord, Free Download Manager, kDrive, Kiro, and LM Studio.
Documented day-to-day commands: dynapt update, dynapt list, dynapt clean, and refreshing only the dynapt APT source.
Added troubleshooting notes for logs, downloads, GitHub rate limits, and port conflicts.
Added source-development and packaging instructions, including ./dynapt and ./build.sh.
Linked back to the original Gist and issue #1 for context.

Implementation alignment

The documentation was checked against the current implementation:

main.js exposes the server/default, clean, list, and update commands.
src/getConfig.js validates the documented fields, makes url and github mutually exclusive, requires jq to be used with url, and generates id automatically.
src/updatePackages.js implements ETag/GitHub release caching, package download, AppImage wrapping, dpkg-scanpackages, and repository metadata generation.
src/server.js serves /Packages, /Release, and files under /data/.
permissions.sh and build.sh define the runtime permissions and packaging workflow.

Validation

Parsed every JSON fenced code block in the README.
Checked that all 42 Markdown code-fence markers are paired.
Ran git diff --check.
Verified both current release assets return HTTP 200:
- dynapt-amd64.deb
- dynapt-arm64.deb
Verified the issue, release page, original Gist, and Deno homes return HTTP 200.
Ran deno check main.js with Deno 2.9.6; type/module checking completed successfully.
Performed a smoke test in an isolated temporary checkout with an empty app list:
- GET /Packages returned HTTP 200 with an empty body.
- GET /Release returned HTTP 200 with the expected hashes for the empty Packages file.
- dynapt list completed successfully.

A fresh Deno 2 run exposed unrelated existing module drift because https://esm.sh/jq-wasm is not pinned and now resolves to a build without a default export. The isolated smoke test used a local-only temporary pin to the previous default-exporting version. That temporary change is not included in this pull request. The selected work item is the missing README, so this PR intentionally keeps the change documentation-only.

Contribution checklist

Branch is based on the current default branch, master.
Commit and pull request target the upstream repository, KaKi87/dynapt.
The change is scoped to issue #1 and does not alter runtime behavior.
The README instructions were reviewed against the current source.
Static documentation checks and an empty-repository smoke test were run.

There is no repository-specific CONTRIBUTING.md or automated test/lint command in the repository, so this follows the standard fork, branch, verify, and pull-request workflow.

## Summary Closes #1. This makes the repository self-contained by expanding `README.md` with the experimental setup guide that currently lives in a Gist. The documentation is adapted to match the current code paths and repository layout. No functional application code is changed. ## What changed - Documented the project scope, supported architectures, runtime commands, and experimental status. - Added installation instructions for the current development release and both Debian packages. - Documented configuration in `/opt/dynapt/config.json`, including `port`, `concurrency`, `apps`, and `githubAccessToken`. - Added APT source setup, server startup, and boot-time startup instructions. - Documented application configuration for: - direct DEB downloads, - direct AppImage downloads and the optional `appimage.bin` command link, - GitHub releases, including `repo`, `filter`, and `prerelease`, - `jq` filters for metadata endpoints that return a package URL, - automatic `id` generation and cache behavior. - Added complete direct-download examples for Discord, Free Download Manager, kDrive, Kiro, and LM Studio. - Documented day-to-day commands: `dynapt update`, `dynapt list`, `dynapt clean`, and refreshing only the dynapt APT source. - Added troubleshooting notes for logs, downloads, GitHub rate limits, and port conflicts. - Added source-development and packaging instructions, including `./dynapt` and `./build.sh`. - Linked back to the original Gist and issue #1 for context. ## Implementation alignment The documentation was checked against the current implementation: - `main.js` exposes the server/default, `clean`, `list`, and `update` commands. - `src/getConfig.js` validates the documented fields, makes `url` and `github` mutually exclusive, requires `jq` to be used with `url`, and generates `id` automatically. - `src/updatePackages.js` implements ETag/GitHub release caching, package download, AppImage wrapping, `dpkg-scanpackages`, and repository metadata generation. - `src/server.js` serves `/Packages`, `/Release`, and files under `/data/`. - `permissions.sh` and `build.sh` define the runtime permissions and packaging workflow. ## Validation - Parsed every JSON fenced code block in the README. - Checked that all 42 Markdown code-fence markers are paired. - Ran `git diff --check`. - Verified both current release assets return HTTP 200: - `dynapt-amd64.deb` - `dynapt-arm64.deb` - Verified the issue, release page, original Gist, and Deno homes return HTTP 200. - Ran `deno check main.js` with Deno 2.9.6; type/module checking completed successfully. - Performed a smoke test in an isolated temporary checkout with an empty app list: - `GET /Packages` returned HTTP 200 with an empty body. - `GET /Release` returned HTTP 200 with the expected hashes for the empty `Packages` file. - `dynapt list` completed successfully. A fresh Deno 2 run exposed unrelated existing module drift because `https://esm.sh/jq-wasm` is not pinned and now resolves to a build without a default export. The isolated smoke test used a local-only temporary pin to the previous default-exporting version. That temporary change is not included in this pull request. The selected work item is the missing README, so this PR intentionally keeps the change documentation-only. ## Contribution checklist - [x] Branch is based on the current default branch, `master`. - [x] Commit and pull request target the upstream repository, `KaKi87/dynapt`. - [x] The change is scoped to issue #1 and does not alter runtime behavior. - [x] The README instructions were reviewed against the current source. - [x] Static documentation checks and an empty-repository smoke test were run. There is no repository-specific `CONTRIBUTING.md` or automated test/lint command in the repository, so this follows the standard fork, branch, verify, and pull-request workflow.

forkfixer-kaki added 1 commit 2026-10-27 21:50:04 +01:00