f9acdef3fe
- CHANGELOG.md following Keep a Changelog; 0.1.0 entry covers all features shipped through the loaded-model indicator - build.sh now also tags the image with the version read from pyproject.toml, e.g. rg.nl-ams.scw.cloud/valinor/finrod:0.1.0 - README documents the release workflow (edit CHANGELOG, bump pyproject version, merge, tag vX.Y.Z, build, bump valinor)
76 lines
2.5 KiB
Markdown
76 lines
2.5 KiB
Markdown
# finrod
|
||
|
||
Tiny web translator backed by Ollama on radagast. Named for Finrod Felagund, Noldor loremaster of the tongues of Men.
|
||
|
||
## Run
|
||
|
||
```sh
|
||
uv run uvicorn app:app --host 127.0.0.1 --port 8000 --reload
|
||
```
|
||
|
||
Then open http://127.0.0.1:8000.
|
||
|
||
## Config
|
||
|
||
| Env var | Default | Notes |
|
||
|---|---|---|
|
||
| `OLLAMA_URL` | `http://radagast.jpnadas.xyz:11434` | Ollama base URL |
|
||
| `MODEL_FILTER` | `gemma,aya` | Comma-separated substrings; model matches if it contains any. Empty = show all |
|
||
|
||
## Models
|
||
|
||
For Pt/Nl/En translation, three worth A/B-ing:
|
||
|
||
```sh
|
||
ssh radagast 'ollama pull gemma2:9b' # already there — big-and-broad baseline
|
||
ssh radagast 'ollama pull gemma3:4b' # newer multilingual training, ~2-3× faster on Ivy Bridge
|
||
ssh radagast 'ollama pull aya-expanse:8b' # Cohere multilingual model, strong on Dutch
|
||
```
|
||
|
||
All three fit in radagast's 10 GB at Q4. Switching models in the dropdown forces Ollama to load the new weights — expect a 5-15 s pause on the first call after a switch while it reads from disk.
|
||
|
||
## Build / push image
|
||
|
||
Built locally and pushed to Scaleway — no Gitea runners on the homelab yet, so there's no CI workflow.
|
||
|
||
One-time setup (host needs buildx + QEMU for cross-arch):
|
||
|
||
```sh
|
||
docker buildx create --name multi --use
|
||
docker run --privileged --rm tonistiigi/binfmt --install all
|
||
docker login rg.nl-ams.scw.cloud -u nologin -p <SCW_SECRET_KEY>
|
||
```
|
||
|
||
Then on every change:
|
||
|
||
```sh
|
||
./build.sh
|
||
```
|
||
|
||
That builds `linux/amd64,linux/arm64` and pushes three tags:
|
||
- `:latest` — moving pointer
|
||
- `:<git-short-sha>` — immutable, traceable
|
||
- `:<pyproject-version>` (e.g. `:0.1.0`) — semver
|
||
|
||
## Deploy
|
||
|
||
Cluster manifests live in `valinor/apps/finrod/` (bjw-s app-template, internal-only ingress at `finrod.jpnadas.xyz`). To roll out a new build, bump `tag:` in `valinor/apps/finrod/values.yaml` to the new semver on a branch → PR → merge → ArgoCD syncs.
|
||
|
||
## Release workflow
|
||
|
||
This project uses [Semantic Versioning](https://semver.org/) and keeps a human-edited [CHANGELOG.md](./CHANGELOG.md).
|
||
|
||
To cut a release:
|
||
|
||
1. On a branch, edit `CHANGELOG.md`: move accumulated `[Unreleased]` notes into a new `## [X.Y.Z] - YYYY-MM-DD` section.
|
||
2. Bump `version` in `pyproject.toml` to `X.Y.Z`.
|
||
3. PR → merge to `main`.
|
||
4. Tag the merge commit:
|
||
```sh
|
||
git checkout main && git pull
|
||
git tag -a vX.Y.Z -m "vX.Y.Z"
|
||
git push origin vX.Y.Z
|
||
```
|
||
5. `./build.sh` — the image now also gets `:X.Y.Z` (read from `pyproject.toml`).
|
||
6. In `valinor`, bump `apps/finrod/values.yaml` `tag:` from the previous version to `X.Y.Z` on a branch → PR → ArgoCD picks it up.
|