# Schemalagd WCX-uppdatering

## Syfte

Systemd-jobbet uppdaterar regelbundet WCX-projektets lokala sajtindex och
facitdatabas samt behandlar väntande OCR-poster. Jobbet körs som användaren
`urban`.

Systemd startar först:

- `/storage/disk1/WCX/scripts/scheduled_update_wcx.sh`

Wrappern avgör om en uppdatering ska göras och anropar därefter:

- `/storage/disk1/WCX/scripts/update_wcx.sh`

`update_wcx.sh` hämtar sajtindexet, importerar metadata till SQLite och kör
OCR-flödet.

## Installerade systemd-filer

Konfigurationen består av:

- service: `/etc/systemd/system/wcx-update.service`
- timer: `/etc/systemd/system/wcx-update.timer`
- miljöfil: `/etc/wcx/update-wcx.env`

Servicen körs som `urban`. Miljöfilen innehåller
`GOOGLE_VISION_API_KEY` och ska ägas av `root:root` med rättigheten
`0600`. Den faktiska API-nyckeln får aldrig läggas i Git, skrivas in i detta
dokument eller visas i terminalutdata och loggar.

Exempel på miljöfilens format, utan verkligt nyckelvärde:

```text
GOOGLE_VISION_API_KEY=<hemligt värde>
```

## Schema och körningsskydd

Timern kontrollerar varje natt klockan 03:30 om jobbet ska startas:

```ini
OnCalendar=*-*-* 03:30:00
Persistent=true
```

`scheduled_update_wcx.sh` kontrollerar tidsstämpeln i
`database/last_scheduled_update`. Den fullständiga uppdateringen körs endast
om minst 47 timmar har gått sedan den senaste lyckade schemalagda körningen.
Tidsstämpeln uppdateras först efter att `update_wcx.sh` har lyckats.

`Persistent=true` innebär att systemd försöker ta igen en missad
kalenderkörning efter att datorn har varit avstängd. Wrapperns 47-timmarskontroll
avgör då om själva uppdateringen behöver köras.

`update_wcx.sh` tar ett exklusivt, icke-blockerande `flock`-lås via
`database/update_wcx.lock`. En ny körning avbryts om en annan uppdatering
redan pågår.

## Kontroll och validering

Kontrollera service och timer:

```bash
sudo systemctl status wcx-update.service
sudo systemctl status wcx-update.timer
sudo systemctl list-timers --all wcx-update.timer
```

Validera unit-filerna efter en konfigurationsändring:

```bash
sudo systemd-analyze verify \
    /etc/systemd/system/wcx-update.service \
    /etc/systemd/system/wcx-update.timer
```

Starta en manuell körning genom systemd:

```bash
sudo systemctl start wcx-update.service
```

Den manuella servicekörningen går genom `scheduled_update_wcx.sh`. Om mindre
än 47 timmar har gått sedan senaste lyckade schemalagda körning avslutas den
utan att starta en ny fullständig uppdatering.

Aktivera och starta timern:

```bash
sudo systemctl enable --now wcx-update.timer
```

Stoppa och inaktivera timern:

```bash
sudo systemctl disable --now wcx-update.timer
```

Att stoppa timern stoppar inte automatiskt en servicekörning som redan pågår.
Kontrollera därför servicens status separat innan en pågående körning stoppas.

## Loggar

Scriptens standardutdata och felutdata samlas av systemd-journalen. Jobbet
skriver ingen separat loggfil.

Visa hela serviceloggen:

```bash
sudo journalctl -u wcx-update.service
```

Följ en pågående körning:

```bash
sudo journalctl -u wcx-update.service -f
```

Visa loggar från den aktuella uppstarten:

```bash
sudo journalctl -b -u wcx-update.service
```

## Filer som jobbet skriver

En fullständig uppdatering kan skriva eller ersätta:

- `/storage/disk1/WCX/import/wcx_site_index.json.tmp`
- `/storage/disk1/WCX/import/wcx_site_index.json`
- `/storage/disk1/WCX/database/wcx.db`
- SQLite-journal- eller WAL-filer bredvid databasen
- `/storage/disk1/WCX/database/update_wcx.lock`
- `/storage/disk1/WCX/database/last_scheduled_update`

Sajtindexet skrivs först till en temporär fil och ersätter sedan den ordinarie
JSON-filen. Import- och OCR-stegen uppdaterar facitdatabasen. Lockfilen används
för att förhindra överlappande körningar, och tidsstämpelfilen används av
wrappern för 47-timmarskontrollen.