Skip to content

Wine Platform Operations Cheat Sheet

Quick operational commands for routine administration on the Raspberry Pi.

Canonical unit names

winecellar-api.service
winecellar-kiosk.service
wine-inventory-stock.service
wine-inventory-stock.timer

Backend

Restart backend

sudo systemctl restart winecellar-api.service

Check backend status

systemctl status winecellar-api.service --no-pager

View backend logs

journalctl -u winecellar-api.service -f
journalctl -u winecellar-api.service -n 100 --no-pager

Edit backend service

sudo nano /etc/systemd/system/winecellar-api.service
sudo systemctl daemon-reload

Test API locally

curl -I http://127.0.0.1:8000/

Open API docs

http://<pi-ip>:8000/docs

Docs

Build docs

cd ~/wine_platform
source /home/pi/venvs/docs/bin/activate
mkdocs build

Rebuild with helper script

~/wine_platform/tools/rebuild_docs.sh

Docs URL

http://<pi-ip>:8088

Docs service

systemctl status wine-platform-docs.service --no-pager
sudo systemctl restart wine-platform-docs.service
journalctl -u wine-platform-docs.service -f

Qt Kiosk

Restart kiosk UI

sudo systemctl restart winecellar-kiosk.service

Check kiosk service

systemctl status winecellar-kiosk.service --no-pager

View kiosk logs

journalctl -u winecellar-kiosk.service -f

Daily Stock Runtime

Production model

wine-inventory-stock.timer
    → wine-inventory-stock.service
        → /home/pi/wine_platform/workers/wine_inventory/src/pince_shelf/cli/stock_runtime.py

Start one batch manually

sudo systemctl start wine-inventory-stock.service

Check timer

systemctl status wine-inventory-stock.timer --no-pager
systemctl list-timers --all | grep wine-inventory-stock

Check service

systemctl status wine-inventory-stock.service --no-pager

View stock runtime logs

journalctl -u wine-inventory-stock.service -f
journalctl -u wine-inventory-stock.service -n 200 --no-pager

Edit daily stock units

sudo nano /etc/systemd/system/wine-inventory-stock.service
sudo nano /etc/systemd/system/wine-inventory-stock.timer
sudo systemctl daemon-reload
sudo systemctl enable --now wine-inventory-stock.timer

Important

Do not use these as the documented production scheduling method:

crontab -e
python src/pince_shelf/vision/stock_runtime.py

Motion Runtime

Manual run only if that script exists in your current codebase:

cd /home/pi/wine_platform/workers/wine_inventory
source .venv/bin/activate
python src/pince_shelf/cli/motion_runtime.py

NAS Data Access

Pi mount path

/mnt/nasWeb/web_images/Stock_vision

Synology internal path

/volume2/web/web_images/Stock_vision

Common runtime folders

/mnt/nasWeb/web_images/Stock_vision/data/snapshots
/mnt/nasWeb/web_images/Stock_vision/data/cells_runtime
/mnt/nasWeb/web_images/Stock_vision/data/cells_runtime_res

Configuration

Shared config directory

/home/pi/wine_platform/shared/config

Important files

shared.env
pince_shelf.env
pince_shelf.ini

Restart Entire Platform

sudo systemctl restart winecellar-api.service
sudo systemctl restart winecellar-kiosk.service
sudo systemctl start wine-inventory-stock.service

Diagnostics

Show platform services

systemctl | egrep 'winecellar|wine-inventory'

Check open ports

sudo lsof -i -P -n
sudo lsof -i :8000

Show Pi IP

hostname -I

Test NAS mount

ls /mnt/nasWeb

Quick mental model

flowchart TD
    API[winecellar-api.service] --> KIOSK[winecellar-kiosk.service]
    TIMER[wine-inventory-stock.timer] --> STOCK[wine-inventory-stock.service]
    STOCK --> SCRIPT[stock_runtime.py]
    SCRIPT --> NAS[NAS data]

Typical debug workflow

  1. Check backend
systemctl status winecellar-api.service --no-pager
  1. Check backend logs
journalctl -u winecellar-api.service -f
  1. Test API
curl http://127.0.0.1:8000/docs
  1. Check kiosk
systemctl status winecellar-kiosk.service --no-pager
  1. Check daily timer
systemctl status wine-inventory-stock.timer --no-pager
  1. Check daily stock logs
journalctl -u wine-inventory-stock.service -n 100 --no-pager
  1. Verify NAS mount
ls /mnt/nasWeb

Summary

The agreed production scheduling solution is:

wine-inventory-stock.timer
    → wine-inventory-stock.service
        → /home/pi/wine_platform/workers/wine_inventory/src/pince_shelf/cli/stock_runtime.py

Backup (NAS)

Model

wine-platform-backup.timer → wine-platform-backup.service → backup_wine_platform.sh

Manual run

sudo systemctl start wine-platform-backup.service

Check timer

systemctl status wine-platform-backup.timer systemctl list-timers --all | grep wine-platform-backup

Logs

journalctl -u wine-platform-backup.service -n 100 --no-pager

Paths

/mnt/nasData/wine_platform_backup/daily/ /mnt/nasData/wine_platform_backup/safe/

Rules

  • daily automatic
  • keep 5 days
  • safe manual only
  • safe NEVER modified