kroshtan.com — independent ML/AI engineering. FastAPI, server-rendered, deployed to Render from GHCR. https://kroshtan.com
  • Python 52.3%
  • CSS 25.3%
  • HTML 15.3%
  • JavaScript 4.3%
  • Makefile 1.6%
  • Other 1.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
kroshtan 04dcdfeec6
All checks were successful
CI / CD / check (push) Successful in 36s
CI / CD / deploy (push) Successful in 22s
Merge pull request 'Deploy: kamal-proxy keeps no request log (log driver none)' (#1) from proxy-no-request-logs into main
2026-11-18 11:04:10 +00:00
.forgejo/workflows Deploy: LLM_API_KEY comes from the Forgejo repo secret 2026-10-25 20:03:14 +01:00
.kamal Deploy: LLM_API_KEY comes from the Forgejo repo secret 2026-10-25 20:03:14 +01:00
app Contact: link the GitHub profile, keep code links on Forgejo 2026-10-26 20:59:16 +01:00
config Deploy: kamal-proxy keeps no request log (log driver none) 2026-11-18 12:02:42 +01:00
content Services: the next step after an MVP, not a full platform 2026-10-26 21:17:04 +01:00
private New copy, Scaleway, a privacy page, and Kamal deploys from Forgejo 2026-10-22 11:19:24 +02:00
prompts Services: the next step after an MVP, not a full platform 2026-10-26 21:17:04 +01:00
tests Contact: link the GitHub profile, keep code links on Forgejo 2026-10-26 20:59:16 +01:00
.dockerignore New copy, Scaleway, a privacy page, and Kamal deploys from Forgejo 2026-10-22 11:19:24 +02:00
.gitignore Project tooling: uv, Makefile, ruff/mypy/pydoclint via pre-commit 2026-09-26 20:46:35 +02:00
.pre-commit-config.yaml Project tooling: uv, Makefile, ruff/mypy/pydoclint via pre-commit 2026-09-26 20:46:35 +02:00
.python-version Project tooling: uv, Makefile, ruff/mypy/pydoclint via pre-commit 2026-09-26 20:46:35 +02:00
Dockerfile New copy, Scaleway, a privacy page, and Kamal deploys from Forgejo 2026-10-22 11:19:24 +02:00
LICENSE Project tooling: uv, Makefile, ruff/mypy/pydoclint via pre-commit 2026-09-26 20:46:35 +02:00
Makefile Project tooling: uv, Makefile, ruff/mypy/pydoclint via pre-commit 2026-09-26 20:46:35 +02:00
pyproject.toml New copy, Scaleway, a privacy page, and Kamal deploys from Forgejo 2026-10-22 11:19:24 +02:00
README.md Services: drop the three packages, keep the MVP offer 2026-10-26 20:58:52 +01:00
uv.lock New copy, Scaleway, a privacy page, and Kamal deploys from Forgejo 2026-10-22 11:19:24 +02:00

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 (from content/, with TODO placeholders stripped) and the private notes.
  • Context: public content from content/about.md and about/skills/services/portfolio.yaml, plus every .md/.txt file in private/ (or $PRIVATE_DIR). Information from private files can appear in answers.
  • Feature switch: the box is only rendered when LLM_API_KEY is set. Without it the site works as before and /api/ask answers 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. check runs in an unprivileged container with no docker access and no secrets. deploy runs only on pushes to main, 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 versions lists 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 MX records (mail.protonmail.ch, mailsec.protonmail.ch), the SPF TXT record on @, the Proton verification TXT record, the DKIM CNAME records (protonmail._domainkey, protonmail2._domainkey, protonmail3._domainkey) and the DMARC TXT record on _dmarc. Never put a CNAME on the apex: it would knock out the MX, SPF and verification records and stop email for the whole domain.