- Python 52.3%
- CSS 25.3%
- HTML 15.3%
- JavaScript 4.3%
- Makefile 1.6%
- Other 1.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo/workflows | ||
| .kamal | ||
| app | ||
| config | ||
| content | ||
| private | ||
| prompts | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| .pre-commit-config.yaml | ||
| .python-version | ||
| Dockerfile | ||
| LICENSE | ||
| Makefile | ||
| pyproject.toml | ||
| README.md | ||
| uv.lock | ||
kroshtan.com
The website of Kroshtan, the sole proprietorship of Floris van Beers, an independent ML/AI engineer in
Groningen. Python + FastAPI, server-rendered Jinja templates, one small stylesheet and a few lines of vanilla
JavaScript. No frontend framework, no trackers, no third-party requests from the browser. One API endpoint,
POST /api/ask, lets visitors check whether their problem is a fit; it calls an OpenAI-compatible LLM API
(Scaleway Generative APIs, Paris) from the server.
MIT licensed; see LICENSE. The fonts (Fraunces, Source Sans 3) are self-hosted under the SIL
Open Font License; see app/static/fonts/.
app/ FastAPI app, templates, static assets
content/ all copy (YAML + Markdown), edit these to change the site
prompts/ assess.md, the system prompt for "Can I help with this?"
private/ extra context for that assistant (gitignored, except its README)
tests/ pytest suite
Dockerfile the image that runs in production
config/ deploy.yml, the Kamal deploy config
.kamal/ secrets: which environment variables Kamal reads (names only, never values)
.forgejo/ CI/CD on Forgejo Actions: lint + tests, then build and deploy with Kamal
Run locally
Requires Python 3.12+ and make.
make install # one-time: venv (with uv inside it), dependencies, pre-commit hook
make dev # http://localhost:8000, reloads on changes to app/ and content/
Other targets (make help lists them all):
make test # pytest with coverage
make fix # pre-commit on all files: ruff, ruff-format, mypy, pydoclint
make todos # every TODO placeholder still left in content/
Or run the production image: docker build -t kroshtan-web . && docker run -p 10000:10000 kroshtan-web.
Editing content
Every piece of copy on the site is in content/. Templates only hold fixed interface labels, such as
"Skip to content", "Source code" and the 404 page.
| File | Page |
|---|---|
site.yaml |
name, email, links, KvK number, VAT ID, navigation |
home.yaml |
home page |
about.yaml, about.md |
about page: facts and timeline (YAML), prose (Markdown) |
skills.yaml |
skill groups |
services.yaml |
the launch offer and bigger or hourly work (full copy + the short home-page summary) |
portfolio.yaml |
projects, publications |
contact.yaml |
contact page |
privacy.yaml, privacy.md |
privacy statement: title (YAML), prose (Markdown) |
Long fields are Markdown. Any value starting with TODO is shown on the page with a yellow highlight so
nothing unfinished can go live unnoticed; make todos lists them.
KvK number and VAT ID. Dutch law requires both the Chamber of Commerce number and the VAT ID
(btw-id) on a business website. While kvk_number or vat_id in content/site.yaml is empty, the footer
shows a highlighted TODO and the server logs a warning at startup.
Projects. Add public projects to projects: in content/portfolio.yaml (title, description, url,
tags). An entry with example: true is shown with an "Example" label.
"Can I help with this?"
A text box on the home and contact pages. The visitor describes a problem (max 1,500 characters), the server wraps it in a fixed prompt and asks the model whether it fits Floris's expertise, and the answer streams back into the page.
- Prompt:
prompts/assess.md. Edit freely; it is read at startup. The server appends the contact email, the public site content (fromcontent/, withTODOplaceholders stripped) and the private notes. - Context: public content from
content/about.mdandabout/skills/services/portfolio.yaml, plus every.md/.txtfile inprivate/(or$PRIVATE_DIR). Information from private files can appear in answers. - Feature switch: the box is only rendered when
LLM_API_KEYis set. Without it the site works as before and/api/askanswers 503. - Privacy: questions are not stored or logged. Logs contain counts only ("question 12 of 100 today"). Rate-limit buckets are keyed by a salted hash of the IP, kept in memory, and the container runs with access logs off. A note under the box tells visitors their question goes to an external AI service.
Configuration
| Variable | Default | Meaning |
|---|---|---|
LLM_API_KEY |
(unset) | API secret key of the LLM provider. Server-side only; never sent to the browser. |
LLM_BASE_URL |
https://api.scaleway.ai/v1 |
The provider's OpenAI-compatible endpoint. Change it (and the key and model) to switch provider. |
LLM_MODEL |
mistral-medium-3.5-128b |
Model to use. Scaleway's docs list the supported models and their end-of-life dates. |
LLM_MAX_TOKENS |
600 |
Output ceiling per answer. The prompt asks for ≤150 words; the rest is headroom. |
DAILY_REQUEST_CAP |
100 |
Questions per UTC day across all visitors. Above it, visitors get a friendly message with the email address. |
RATE_LIMIT_PER_HOUR / RATE_LIMIT_PER_DAY |
5 / 20 |
Per visitor IP, sliding windows. |
PRIVATE_DIR |
private/ |
Folder with private context files. /etc/secrets in production. |
CLIENT_IP_HEADER |
(unset) | Header holding the real client IP, if the edge sets one clients can't forge (e.g. cf-connecting-ip). |
TRUSTED_PROXY_HOPS |
1 |
Otherwise: which X-Forwarded-For entry, counted from the right, is the client. |
Cost: each question sends the system prompt (about 3k tokens; there is no prompt caching) plus the question, and gets
a few hundred tokens back. Scaleway bills per token, see its pricing page; DAILY_REQUEST_CAP bounds the daily total.
Privacy: Scaleway says it doesn't store or train on prompts and outputs, except that it may keep a request for up to
two weeks when it causes an abnormal error or looks malicious. The site's privacy statement (content/privacy.md)
names Scaleway as the processor; update it if you change provider.
Limits are held in memory: correct for the single production container, reset on each deploy or restart.
Running it locally
export LLM_API_KEY=<your Scaleway API secret key>
make dev
Put any private notes in private/ (e.g. private/projects.md). They are picked up on restart.
In production, LLM_API_KEY is a Forgejo repo secret (Settings → Actions → Secrets) that the deploy job
hands to Kamal, and the private notes live on the server, mounted read-only at /etc/secrets
(config/deploy.yml). Neither is ever in the repo or the image. Both are read at startup, so redeploy after
changing them (Actions → Run workflow).
Checking the per-IP limit
The limiter must see the visitor's real address, not one a client can forge. In production the request passes
Cloudflare, Caddy (which replaces X-Forwarded-For with the visitor's address from Cloudflare) and kamal-proxy
(which appends Caddy's), so the visitor is second from the right: TRUSTED_PROXY_HOPS=2. Check it once after
any change to that chain:
# 6th request should be a 429, even though every request claims a different address:
for i in 1 2 3 4 5 6; do
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://kroshtan.com/api/ask \
-H 'Content-Type: application/json' -H "X-Forwarded-For: 203.0.113.$i" \
-d '{"question":"Checking the rate limit, please ignore."}'
done
If all six return 200, the limiter reads a forged address: lower TRUSTED_PROXY_HOPS. If visitors on different
networks hit the limit together, it reads a proxy's address: raise it. The global daily cap bounds cost either
way. (The test uses 5 of your own questions and 5 of today's cap.)
Deployment
push to main ──▶ Forgejo Actions
check (public runner): pre-commit + pytest
deploy (deploy runner): kamal deploy ──▶ build, push to the forge registry
└─▶ start the new container, health check,
kamal-proxy switches traffic, old one stops
The code lives at git.kroshtan.com/kroshtan/kroshtan-web.
Deploys use Kamal: config/deploy.yml says where the site runs and how, and
.kamal/secrets names the two secrets Kamal needs. The server itself is set up from a separate, private
repository.
- Two jobs, two runners.
checkruns in an unprivileged container with no docker access and no secrets.deployruns only on pushes tomain, on a separate runner that holds the deploy credentials. - No downtime. kamal-proxy keeps sending traffic to the old container until the new one answers
/healthz. - Rollback:
kamal rollback <version>, where the version is a commit SHA (kamal app versionslists them). - Redeploy without a code change: Actions → CI / CD → Run workflow on
main.
DNS
kroshtan.com and www.kroshtan.com are proxied by Cloudflare. The apex is canonical; the app redirects www
to it.
Warning
The domain's email runs on Proton Mail. Do not touch Proton's records. Keep the
MXrecords (mail.protonmail.ch,mailsec.protonmail.ch), the SPFTXTrecord on@, the Proton verificationTXTrecord, the DKIMCNAMErecords (protonmail._domainkey,protonmail2._domainkey,protonmail3._domainkey) and the DMARCTXTrecord on_dmarc. Never put aCNAMEon the apex: it would knock out the MX, SPF and verification records and stop email for the whole domain.