Metadata-Version: 2.5
Name: il2ks
Version: 0.1.0
Summary: Self-hosted statistics website for IL-2 Sturmovik: Korea dedicated servers
Project-URL: Homepage, https://github.com/FGlazov/il2_korea_stats
Project-URL: Documentation, https://github.com/FGlazov/il2_korea_stats/tree/main/docs
Project-URL: Issues, https://github.com/FGlazov/il2_korea_stats/issues
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django :: 5.2
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment :: Simulation
Requires-Python: >=3.13
Requires-Dist: django<5.3,>=5.2
Requires-Dist: granian>=2.0
Requires-Dist: pillow>=12.3.0
Requires-Dist: tzdata>=2024.1
Requires-Dist: whitenoise>=6.7
Description-Content-Type: text/markdown

# 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](https://github.com/FGlazov/il2_korea_stats/blob/main/CHANGELOG.md);
please report problems in [Issues](https://github.com/FGlazov/il2_korea_stats/issues). The design lives in
[design_doc/](https://github.com/FGlazov/il2_korea_stats/blob/main/design_doc/README.md).

## Install

- **Windows**: download `il2ks-setup-<version>.exe` from the [latest release](https://github.com/FGlazov/il2_korea_stats/releases/latest)
  and follow [Installing il2ks on Windows](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/install-windows.md).
- **Linux, or by hand**: `uv tool install il2ks` ([PyPI](https://pypi.org/project/il2ks/)), then
  [Installing il2ks by hand](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/install.md).
- **Docker**: [Installing with Docker](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/install-docker.md).

## 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](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/settings.md).
- **Safe by default**: HTTPS with a free certificate, daily backups, a `doctor` command that checks your setup.

Inspired by [IL2 stats](https://github.com/vaal-/il2_stats) by =FB=Vaal and =FB=Isay. See [NOTICE](https://github.com/FGlazov/il2_korea_stats/blob/main/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](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/install-windows.md): the double-click installer (no terminal), service, upgrades.
- [Installing il2ks by hand](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/install.md): Windows and Linux, HTTPS, start at boot, upgrading, troubleshooting with `il2ks doctor`.
- [Installing with Docker](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/install-docker.md): one Compose file for Linux hosts (also DServer under Wine).
- [Using your own proxy (nginx, IIS)](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/reverse-proxy.md): when ports 80/443 are already taken.
- [Rules, scoring and tours](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/settings.md): change a rule or a score, and which command to run afterwards (`reprocess` or `rebuild-aggregates`); upgrading; the admin area.
- [Customizing the site](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/customizing.md): branding in the admin, and replacing templates and files in `custom/`.
- [Template versions and releases](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/releasing.md): for developers; `il2ks dev bump-templates` after changing a template, and how to make a release.
- [Translating il2ks](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/translating.md): review or improve a language, keep translations in step, add a language.
- [Performance testing](https://github.com/FGlazov/il2_korea_stats/blob/main/docs/performance-testing.md): timing and query budgets, front-end budgets and web vitals, Locust load test.

## Development

Requires [uv](https://docs.astral.sh/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](https://github.com/FGlazov/il2_korea_stats/blob/main/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](https://github.com/FGlazov/il2_korea_stats/blob/main/LICENSE) and [NOTICE](https://github.com/FGlazov/il2_korea_stats/blob/main/NOTICE).
