il2ks: IL-2 Sturmovik: Korea stats

Self-hosted statistics website for IL-2 Sturmovik: Korea dedicated servers. It parses the server's mission logs into a database and serves mission, player and sortie stats as a server-rendered website.

Status: public beta, version 0.1.0. Changes are listed in the changelog; please report problems in Issues. The design lives in design_doc/.

Install

• Windows: download il2ks-setup-<version>.exe from the latest release and follow Installing il2ks on Windows.
• Linux, or by hand: uv tool install il2ks (PyPI), then Installing il2ks by hand.
• Docker: Installing with Docker.

What it does

il2ks reads the text mission logs your DServer writes and builds a stats website from them. It is made for IL-2 Sturmovik: Korea servers.

• Missions, players and sorties: every mission with its kills and losses and who won it, a page per player and a timeline per flight.
• Tours: stats per tour (a month by default, or a new tour whenever one side wins a mission, for dynamic campaigns) or all-time. Every tour is a clean slate: Elo, streaks and achievements start over. The site opens on the current tour.
• Leaderboards: air score, ground score, attack proficiency, interception, tank busting, Elo (propeller and jet) and play time. Scoring is yours to tune, including optional points for time in the air, so a quiet patrol counts too.
• Live data: sorties and stats update while the mission is still running.
• Aircraft pages: how each type does, its best loadouts and modifications, and who it beats and loses to, filtered by tour, role and modification.
• Achievements, streaks, killboards (who shot whom), accuracy, assists, and Top 25% / 10% / 5% / 1% marks on a player's best ratios and ratings.
• Your branding: title, logo, colors (light and dark), fonts (also your own font file), menu links, all in the admin without touching files. Templates can be replaced for more.
• Six languages: English, Russian, German, Spanish, French, Brazilian Portuguese. Visitors get their browser's language and can change it in the footer.
• Rules you can switch: for example whether ramming earns a kill, how many points a kill is worth, and what a death costs. See Rules, scoring and tours.
• Safe by default: HTTPS with a free certificate, daily backups, a doctor command that checks your setup.

Inspired by IL2 stats by =FB=Vaal and =FB=Isay. See NOTICE.

For server admins

Written for people who run a game server, not for programmers: short steps, copy-paste commands. On Windows, use the installer. On Linux, use Docker or the manual steps.

• Installing il2ks on Windows: the double-click installer (no terminal), service, upgrades.
• Installing il2ks by hand: Windows and Linux, HTTPS, start at boot, upgrading, troubleshooting with il2ks doctor.
• Installing with Docker: one Compose file for Linux hosts (also DServer under Wine).
• Using your own proxy (nginx, IIS): when ports 80/443 are already taken.
• Rules, scoring and tours: change a rule or a score, and which command to run afterwards (reprocess or rebuild-aggregates); upgrading; the admin area.
• Customizing the site: branding in the admin, and replacing templates and files in custom/.
• Template versions and releases: for developers; il2ks dev bump-templates after changing a template, and how to make a release.
• Translating il2ks: review or improve a language, keep translations in step, add a language.
• Performance testing: timing and query budgets, front-end budgets and web vitals, Locust load test.

Development

Requires uv.

uv sync                       # install Python 3.13 + dependencies
uv run pytest                 # tests on SQLite (default)
uv run ruff check && uv run ruff format --check
uv run pyright                # strict type checking
uv run lint-imports           # core must not import Django
uv run il2ks manage migrate   # create the local SQLite database
uv run il2ks web --dev        # the site on plain http://127.0.0.1:8000 (debug mode; never for a public site)

uv run il2ks run starts everything as an admin would (web + log watcher + Caddy); see docs/install.md. To publish a release: bump __version__ in src/il2ks/__init__.py, tag v<version>, push the tag (.github/workflows/release.yml).

Postgres is only used on the dev side: docker compose -f docker/compose.dev.yaml up -d, then IL2KS_TEST_DB=postgres uv run pytest.

Browser (end-to-end) tests drive the real site in Chromium with Playwright. They are opt-in, so uv run pytest never needs a browser:

uv run playwright install chromium                  # once; on a fresh Linux machine/CI: install --with-deps chromium
IL2KS_TEST_E2E=1 uv run pytest -m e2e               # headless; add --headed --slowmo 300 to watch
IL2KS_TEST_E2E=1 uv run pytest -m e2e --tracing=retain-on-failure --screenshot=only-on-failure   # what CI does
uv run playwright show-trace test-results/<test>/trace.zip

PowerShell: $env:IL2KS_TEST_E2E = "1" first. The tests start il2ks web --dev on a free port with a throw-away data dir filled with made-up players and missions (tests/e2e/world.py), so they never touch your own data. They find things by role, label and visible text, so keep the words on the pages stable or update the tests with them.

License

MIT, see LICENSE and NOTICE.