docs: a README for the repository
What Halkyon Learn is and its three packages with their licences; how to run it locally (the editor fork next to the repository, the git-ignored password file and its keys, serverpod start without analytics, the server URL); the checks and the sync tests; running an instance with deploy/; and where the rules, decisions and licences are. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
This commit is contained in:
parent
231369900b
commit
f841542d1d
GPG key ID:
07F6FCF405488B64
1 changed files with 77 additions and 0 deletions
77
README.md
Normal file
77
README.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
# Halkyon Learn
|
||||
|
||||
A spaced-repetition learning app: studysets of flashcards with rich text, studied offline
|
||||
on every device and synced between a person's devices. Anyone can run an instance.
|
||||
|
||||
- **Offline first.** Each device keeps its own database and syncs in the background
|
||||
(`serverpod_offline_sync`). Edits made on two devices while offline are never lost:
|
||||
card content is stored as append-only revisions, and a side changed differently on two
|
||||
devices is shown as a conflict until the person picks a version
|
||||
([ADR 0001](docs/adr/0001-offline-sync.md), [ADR 0003](docs/adr/0003-card-revisions.md)).
|
||||
- **No sign-up needed.** The app starts with an anonymous account; signing in with GitHub
|
||||
later keeps everything. A GitHub sign-in stores only the numeric GitHub ID.
|
||||
- **No end-to-end encryption.** Content is readable by the operator of the instance, as on
|
||||
Mastodon; whoever trusts no operator can run their own
|
||||
([ADR 0002](docs/adr/0002-no-end-to-end-encryption.md)).
|
||||
|
||||
Targets: Linux, Windows, macOS, Android and iOS. There is no web build.
|
||||
|
||||
## Packages
|
||||
|
||||
| Package | What it is | Licence |
|
||||
|---|---|---|
|
||||
| `halkyon_learn_server` | The [Serverpod](https://serverpod.dev) server: endpoints, models, migrations | SSPL-1.0 |
|
||||
| `halkyon_learn_client` | The client, generated from the server's models | AGPL-3.0-or-later |
|
||||
| `halkyon_learn_flutter` | The app (`app.halkyon.learn`) | AGPL-3.0-or-later |
|
||||
|
||||
## Running it locally
|
||||
|
||||
You need Flutter (Dart v3.13 or later) and the Serverpod CLI v4.0.3
|
||||
(`dart install serverpod_cli@4.0.3`). Linux builds also need `libwebkit2gtk-4.1-dev` and
|
||||
`libsecret-1-dev`. The rich-text editor comes from a fork that is expected at
|
||||
`../appflowy-editor`, next to this repository, until the fork is hosted.
|
||||
|
||||
The server's secrets live in `halkyon_learn_server/config/passwords.yaml`, which is never
|
||||
committed. In a fresh clone, create it with a `development` and a `test` section, each
|
||||
holding `database`, `serverSideSessionKeyHashPepper` and `serviceSecret` (for example from
|
||||
`openssl rand -base64 32`). GitHub sign-in is optional: add `githubClientId` and
|
||||
`githubClientSecret` of your own GitHub OAuth app to `development`, registered with the
|
||||
callback URLs `app.halkyon.learn://github-callback` and `http://127.0.0.1/github-callback`.
|
||||
|
||||
Then start the server, its embedded database and the app:
|
||||
|
||||
```sh
|
||||
cd halkyon_learn_server
|
||||
serverpod --no-analytics start
|
||||
```
|
||||
|
||||
`serverpod start` applies pending migrations and reloads on changes. The app talks to the
|
||||
server named by `--dart-define=SERVER_URL=…`, or else to the one in
|
||||
`halkyon_learn_flutter/assets/config.json` (`http://localhost:8080`). Without
|
||||
`--no-analytics`, the Serverpod CLI reports usage to Serverpod.
|
||||
|
||||
## Tests
|
||||
|
||||
```sh
|
||||
tool/check.sh
|
||||
```
|
||||
|
||||
runs the format check, the analyzer with the strict lints of `leancode_lint`, the server's
|
||||
tests (against an embedded PostgreSQL, no Docker needed) and the app's tests. To run it
|
||||
before every push: `ln -s ../../tool/check.sh .git/hooks/pre-push`.
|
||||
|
||||
The sync tests need a running server (`serverpod start`); run them in
|
||||
`halkyon_learn_flutter` with `flutter test -t requires-server`.
|
||||
|
||||
## Running an instance
|
||||
|
||||
`deploy/` holds a Docker Compose setup: Caddy (HTTPS), the server and PostgreSQL. Copy
|
||||
`deploy/.env.example` to `deploy/.env` and fill it in; it explains every value. The
|
||||
licences require offering the source of what the instance runs to the people who use it.
|
||||
|
||||
## More
|
||||
|
||||
- [`AGENTS.md`](AGENTS.md): how the code is organised and the rules it follows.
|
||||
- [`docs/adr/`](docs/adr/): the architecture decisions and their reasons.
|
||||
- [`CONTRIBUTING.md`](CONTRIBUTING.md): licences of contributions and the sign-off.
|
||||
- [`LICENSE.md`](LICENSE.md): which licence covers what.
|
||||
Loading…
Reference in a new issue