first_commit

docs/operations.md

@@ -0,0 +1,105 @@
+# Operations
+
+## Web UI
+
+Start the web UI daemon:
+
+```bash
+python3 -m gibil.scripts.web_daemon
+```
+
+The daemon listens on:
+
+```text
+http://0.0.0.0:8080
+```
+
+By default the server binds to all network interfaces so it can be reached from another machine. Override the bind address or port if needed:
+
+```bash
+export ASTRAPE_WEB_HOST='0.0.0.0'
+export ASTRAPE_WEB_PORT='8080'
+```
+
+The host process reloads `webui.py` and display modules on each request. The browser polls `/api/ui-version` and refreshes when those files change.
+
+## Systemd Services
+
+Install service units:
+
+```bash
+sudo cp deploy/systemd/astrape-web.service /etc/systemd/system/
+sudo cp deploy/systemd/astrape-db.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now astrape-web.service astrape-db.service
+```
+
+Check status:
+
+```bash
+systemctl status astrape-web.service
+systemctl status astrape-db.service
+journalctl -u astrape-web.service -f
+journalctl -u astrape-db.service -f
+```
+
+Both services run as the IPA-managed `gibil` user from `/mnt/astrape`.
+
+## Database Daemon
+
+Install runtime dependencies:
+
+```bash
+python3 -m pip install -r requirements.txt
+```
+
+Create a local env file:
+
+```bash
+cp env/astrape.env.example env/astrape.env
+nano env/astrape.env
+```
+
+Required values:
+
+```text
+ASTRAPE_DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/DBNAME
+ASTRAPE_LATITUDE=59.0000
+ASTRAPE_LONGITUDE=18.0000
+```
+
+Optional values:
+
+```text
+ASTRAPE_WEATHER_FORECAST_HOURS=48
+ASTRAPE_WEATHER_POLL_SECONDS=3600
+ASTRAPE_WEATHER_TRUTH_LOOKBACK_DAYS=14
+ASTRAPE_WEATHER_TRUTH_END_DELAY_DAYS=5
+```
+
+The daemons load `env/*.env` automatically. Existing process environment variables win over file values.
+
+For temporary frontend tuning, enable display-only sample weather data:
+
+```text
+ASTRAPE_WEB_SAMPLE_DATA=1
+```
+
+This does not write artificial data to TimescaleDB. It only changes the web UI weather API response.
+
+Start the database ingest daemon:
+
+```bash
+python3 -m gibil.scripts.db_daemon
+```
+
+Current behavior:
+- initializes TimescaleDB weather tables
+- fetches real Open-Meteo hourly forecasts
+- normalizes them through `WeatherBuilder`
+- stores rows in `weather_forecast_points`
+- fetches Open-Meteo archive data for resolved truth
+- stores rows in `weather_resolved_truth`
+- repeats every `ASTRAPE_WEATHER_POLL_SECONDS`
+
+No internal weather predictions are generated here. This daemon only stores external forecast and resolved-truth data for later modules.