Shanraq (shanraq.org) is a modular Go platform that fuses three things regional media has always kept apart: trustworthy local journalism, free technical courses written in Kazakh as a first language, and a modern classifieds marketplace (real estate first, autos and more to come). It is built to keep reaching readers even when a single channel is blocked — through automatic syndication to Telegram and RSS — and to run three languages as one publication, not three separate sites.
The name refers to the shanyrak — the crown of the Kazakh yurt — the living centre that holds the whole roof together.
Why it exists
- Resilience over dependence. Content is pushed to Telegram and RSS automatically on publish, so the audience stays reachable even if the website is unavailable.
- One roof, not five apps. News, real estate, and (next) autos and a marketplace live in a single product instead of scattered across separate sites and apps.
- AI that removes drudgery, not judgement. Optional machine translation turns one journalist's work into a trilingual, SEO-ready, auto-distributed publication. The platform does not write or edit for the author: the text is theirs, and so is the byline.
- Teaching in a language that has little of it. A programming course in Kazakh is close to nonexistent, so the courses here are written in all three languages at once and given away: open in full, no account, no "first lesson free".
- Built for a small, open economy. Trilingual (kk/ru/en) with per-language SEO (hreflang, sitemaps, structured data), data stored in-country, self-hostable on a single VPS.
Features
- 📰 Trilingual publishing — one article, three language variants; per-language
hreflang, sitemaps and JSON-LD.
- 🎓 Free courses — Go (50 lessons), Python (55 lessons) and SQL (13 lessons), plus Rust: from zero to your own organizer, released five lessons at a time in Kazakh, Russian and English. Rust lessons 1–15 and a preface are prepared for publication in all three languages. Sources live in
course/lessons/; Rust examples and exercise answers are checked on Windows, macOS and Linux. Lessons belong to course contents and are excluded from the main article feed. See the Rust publication procedure.
- 🏠 Real-estate classifieds — listings with photos, geo, amenities, promotion/feature tariffs, and a dedicated listings sitemap.
- 🤖 AI translation & moderation — provider-agnostic (Claude, ChatGPT or Kimi), off unless a key is set. Translation keeps the author's Markdown and links; the platform then compares the result against the original and reports anything mechanically lost, so an author can check a language they do not read.
- 🌤 Weather and the daily archive — every settlement with coordinates has its own forecast page (
/weather/kachar): conditions now, an hourly chart for two days, the chance of rain, and the week ahead. A reader who told their profile where they live is taken to their own town. Every day of publishing has an address too (/archive/2026-08-25), and both feed the sitemap.
- 📍 Advertising priced by reach — an advertiser buys a place, not the whole country, and pays by the square root of the population share it covers: 135,000 ₸ nationwide for a month of the top banner, 27,000 ₸ for one region, 2,889 ₸ for a village. The card is anchored at half what a comparable outlet charges for a comparable placement. The banner runs on that place's pages and on everything inside it. No impression count is promised and no reader is located — the targeting is by what a page is about.
- 📣 Block-resilient syndication — RSS always on; Telegram carries the channel and the bot separately. A channel cannot show two subscribers different things, so it takes only what is written for everyone; anything addressed to a place goes through the bot, which asks the reader once where they live and then delivers by the same containment rule the site's feed uses — a region's news reaches everyone inside it, a village's reaches that village alone.
- 🖼️ Media pipeline — upload, EXIF-strip, brand-watermark; pluggable storage (filesystem now, S3/MinIO ready).
- ⭐ Ratings & author karma — weighted voting with anti-brigading.
- ◎ Prediction ledger — every forecast recorded with its date and judged in public at
/predictions, misses included; the score is allowed to go down.
- 🔎 Built to be cited — sitemaps, IndexNow, conditional GET, a ready-made reference under every article, and an
llms.txt that offers assistants only the human-written work.
- 🔗 Referral loop — invite links, attribution, and promotion-credit rewards.
- 🛠️ Operator admin panel — edit legal/info pages, tariffs, service flags, payment provider, and AI settings without a redeploy.
- 📊 Privacy-respecting analytics — aggregate-only audience metrics; bots separated from humans; traffic sources; no per-visitor profiling.
- 🔐 Secure auth — refresh-token rotation, RBAC, password-reset flows, CSRF protection.
Tech stack
| Layer | Choice |
|---|
| Language | Go 1.26 (modular monolith) |
| Database | PostgreSQL 16 via pgxpool, embedded Goose migrations |
| Web | Server-rendered html/template, progressive enhancement |
| Config | Viper — typed, env-first (SHANRAQ_*), no secrets in git |
| Observability | Zap structured logging, Prometheus metrics, health/readiness probes |
| Delivery | Docker Compose + Caddy (automatic HTTPS) on a single VPS |
| AI | Anthropic Claude (optional, provider-agnostic) |
Quick start (Docker Compose + automatic HTTPS)
git clone https://github.com/DauletBai/shanraq.org.git
cd shanraq.org
cp .env.example .env
# edit .env: POSTGRES_PASSWORD, DOMAIN, SHANRAQ_PUBLIC_BASE_URL,
# SHANRAQ_AUTH_TOKEN_SECRET (>=32 random chars), operator details.
docker compose -f docker-compose.prod.yml up -d --build
Migrations run on first boot; only Caddy is exposed publicly, and it fetches a TLS
certificate automatically. Secrets live only in .env (git-ignored) — in
environment=production the app refuses to start with a weak token secret or a
non-HTTPS base URL. Full guide: docs/DEPLOYMENT.md.
Local development:
make run # start the app
make test # unit tests
make smoke # smoke test
Architecture
A single Go binary composed of independent modules that implement the
shanraq.Module contract (init / start / routes):
articles · shop · payments · auth · ai · media · syndicate · notifier · jobs · ratings · migrations
Each module wires its own routes, migrations, and background workers, so features
compose without a service mesh.
pkg/site is the page frame every module shares: the three languages, the UI
dictionary, the header, the aside, the footer, and one template set that modules
add their own pages to. The dependency points one way — a module knows about the
frame, the frame knows nothing about a module, and a test parses the frame with
no module registered to keep it that way.
A new subject is a new module. pkg/modules/articles grew to 171 files
because every new thing the site did was added beside the last one; a test now
holds it to a ceiling that can only be lowered. Something with its own tables,
its own pages and its own vocabulary belongs in a package with its own name.
See docs/ for the configuration reference, module guides, and
deployment runbook.
Documentation
Security
Secrets never live in the repository — configuration is env-first and .env is
git-ignored. To report a vulnerability, see SECURITY.md
(please do not open a public issue for security reports).
Status & versioning
Live in production at shanraq.org. Releases follow
Semantic Versioning; see CHANGELOG.md.
VERSION is the single release decision. At a project milestone, update it and
its matching CHANGELOG section, let main pass CI, then run the Release
workflow manually. It creates the annotated tag and GitHub Release; ordinary
content commits do not cut releases. Re-running it is safe.
License
Two licences, because the platform and what is taught on it are different
things.
The platform is proprietary — all rights reserved. The source is published
for transparency and review; it is not open-source and may not be used,
deployed, or redistributed without written permission. See LICENSE.
The course materials are open. Lesson texts and lesson maps under
web/static/course/ are CC BY 4.0; the code examples printed inside the
lessons are MIT. A course whose examples may not be run teaches nothing, so
they are released on terms that let a reader copy, run and adapt them. See
LICENSE-COURSE.
For partnership or commercial-use inquiries: [email protected].
