📝 Add a self-contained README (closes #1) #3

Closed
upfixb02rkd wants to merge 1 commit from upfixb02rkd/dynapt:docs/issue-1-self-contained-readme into master
First-time contributor

Problem

Closes #1 ("Readme?"). The repository root shipped only a 40-byte README.md stub, and the full setup/usage documentation lived in a random gist that readers had to find through an issue comment. New users had no in-repo way to learn how to install, configure, run or recover dynapt.

Root cause

Documentation was never committed to the repository; the tutorial was written as an external gist and linked ad-hoc from an issue. There was no contributor-facing reference for the actual CLI and configuration surface.

Solution

Replace the placeholder README.md with a single self-contained guide. The content regrounds the gist on the current source (main.js, src/, lib/) and covers:

  • What dynapt is and isn't — a local dynamic APT repository fronting APT, not a package manager (vs. deb-get and AM).
  • Installation: prebuilt amd64/arm64 DEBs published at /opt/dynapt; also source build/run with Deno.
  • Configuration: config.json schema — port, concurrency, apps, githubAccessToken; per-app name, url/github (repo/filter/prerelease), appimage (with bin), jq, and the auto-generated Joi-validated id used as cache key.
  • Usage: APT source entry, starting the server (dynapt/serve) and @reboot autostart; every CLI command from main.js — serve, list, update, clean, version.
  • A short "how it works" pipeline (resolve → download/wrap → dpkg-scanpackages → apt-ftparchive Release).
  • The tested FOSS and proprietary app examples, troubleshooting (log path, clean, update, targeted apt update), a project layout table, and roadmap/status.

Only README.md is changed (additive documentation). No code, build scripts or configuration were touched.

Verification (run locally in this checkout)

  • bash -n build.sh permissions.sh dynapt — all OK.
  • Parsed all 6 fenced JSON examples successfully.
  • Validated every relative ./path link in the README resolves to an existing file (15 targets); all pass.
  • Checked required sections, full heading hierarchy (no level jumps), and Markdown table column consistency (4 tables, all ragged-group-free).
  • Git state: branch docs/issue-1-self-contained-readme was cut from master at 9b8fa75; commit range relative to upstream/master is exactly one commit touching only README.md (1 file, +328/-1).

Deno is not installed in the contribution sandbox, so the live server/CLI could not be executed here; documentation text was cross-checked directly against main.js, src/ and lib/ instead.

Impact scope

  • Files changed: README.md only.
  • Runtime behavior: none; no executable, dependency or build output changes.
  • Compatibility: documentation only; no breaking change.
  • Needs a maintainer to review/clarify any wording against upstream intent (especially the status/roadmap and tested-app links).

🤖 Generated with Flcast Code / CLIAgent for the fork-based open source contribution exercise.

## Problem Closes #1 ("Readme?"). The repository root shipped only a 40-byte `README.md` stub, and the full setup/usage documentation lived in a random [gist](https://gist.github.com/KaKi87/f620788e9901abbfef4978eb7ad358b4) that readers had to find through an issue comment. New users had no in-repo way to learn how to install, configure, run or recover dynapt. ## Root cause Documentation was never committed to the repository; the tutorial was written as an external gist and linked ad-hoc from an issue. There was no contributor-facing reference for the actual CLI and configuration surface. ## Solution Replace the placeholder `README.md` with a single self-contained guide. The content regrounds the gist on the current source (`main.js`, `src/`, `lib/`) and covers: - What dynapt is and isn't — a local dynamic APT repository fronting APT, not a package manager (vs. deb-get and AM). - Installation: prebuilt `amd64`/`arm64` DEBs published at `/opt/dynapt`; also source build/run with Deno. - Configuration: `config.json` schema — `port`, `concurrency`, `apps`, `githubAccessToken`; per-app `name`, `url`/`github` (repo/filter/prerelease), `appimage` (with `bin`), `jq`, and the auto-generated Joi-validated `id` used as cache key. - Usage: APT source entry, starting the server (`dynapt`/`serve`) and `@reboot` autostart; every CLI command from `main.js` — `serve`, `list`, `update`, `clean`, `version`. - A short "how it works" pipeline (resolve → download/wrap → `dpkg-scanpackages` → `apt-ftparchive` `Release`). - The tested FOSS and proprietary app examples, troubleshooting (log path, `clean`, `update`, targeted `apt update`), a project layout table, and roadmap/status. Only `README.md` is changed (additive documentation). No code, build scripts or configuration were touched. ## Verification (run locally in this checkout) - `bash -n build.sh permissions.sh dynapt` — all OK. - Parsed all 6 fenced JSON examples successfully. - Validated every relative `./path` link in the README resolves to an existing file (15 targets); all pass. - Checked required sections, full heading hierarchy (no level jumps), and Markdown table column consistency (4 tables, all ragged-group-free). - Git state: branch `docs/issue-1-self-contained-readme` was cut from `master` at `9b8fa75`; commit range relative to upstream/master is exactly one commit touching only `README.md` (1 file, +328/-1). Deno is not installed in the contribution sandbox, so the live server/CLI could not be executed here; documentation text was cross-checked directly against `main.js`, `src/` and `lib/` instead. ## Impact scope - **Files changed:** `README.md` only. - **Runtime behavior:** none; no executable, dependency or build output changes. - **Compatibility:** documentation only; no breaking change. - Needs a maintainer to review/clarify any wording against upstream intent (especially the status/roadmap and tested-app links). 🤖 Generated with Flcast Code / CLIAgent for the fork-based open source contribution exercise.
upfixb02rkd added 1 commit 2026-11-20 15:16:21 +01:00
Resolves KaKi87/dynapt#1: consolidate the tutorial gist into the repository root and document the project accurately against the current implementation:

- Describe dynapt's purpose and its relationship to deb-get/AM (it fronts APT, it is not a package manager).
- Document installation (prebuilt DEBs to /opt/dynapt), configuration schema (port/concurrency/apps/githubAccessToken, app url/github/appimage/jq/id), APT source and startup/autostart setup.
- Reference every CLI command from main.js (serve, list, update, clean, version).
- Explain the pipelines (Fetch -> download wrap -> dpkg-scanpackages -> apt-ftparchive Release).
- Fold in the tested FOSS/proprietary app examples, troubleshooting, build/run and project layout sections.

Only the placeholder README.md (40 bytes) is replaced; no code changed.
Owner

Hi,

As explained in #1 and in PR #2, the current shape of this project is temporary, so I won't add docs now for something temporary.

Thank you

Hi, As explained in #1 and in PR #2, the current shape of this project is temporary, so I won't add docs now for something temporary. Thank you
KaKi87 closed this pull request 2026-11-20 19:51:49 +01:00

Pull request closed

Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: KaKi87/dynapt#3
No description provided.