Lager Guru - Runbook

Оперативен наръчник за управление и troubleshooting на Lager Guru приложението.

Съдържание

Стартиране на приложението
Проверка на състоянието
Troubleshooting
Database Restore
Service Worker Cache
VAPID Keys
Логове
Мрежов достъп

Стартиране на приложението

Docker Deployment (Production)

bash

# 1. Навигация към проекта
cd /path/to/lager-guru

# 2. Създай .env файл (ако не съществува)
cat > .env << EOF
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
EOF

# 3. Стартирай приложението
docker compose up -d --build

# 4. Провери статуса
docker compose ps
docker compose logs -f lager-guru

Локална разработка

bash

# 1. Инсталирай зависимости
npm install

# 2. Създай .env.local файл
cat > .env.local << EOF
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
EOF

# 3. Стартирай dev сървър
npm run dev

# 4. Или за production preview
npm run build
npm run preview -- --host --port 8080

Проверка на състоянието

Health Check

bash

# Провери health endpoint
curl http://lager-guru.internal/health.html

# Или в браузър
open http://lager-guru.internal/health.html

Health endpoint проверява:

✅ Статични assets (HTML, CSS, JS)
✅ Supabase връзка (ако е конфигурирана)
⚠️ Auto-refresh на всеки 30 секунди

Docker Status

bash

# Провери статус на контейнерите
docker compose ps

# Провери логове
docker compose logs --tail=100 lager-guru

# Провери ресурси
docker stats

Database Connection

bash

# Провери Supabase connection от CLI
psql "postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres" -c "SELECT version();"

# Или чрез Supabase CLI
supabase status

Troubleshooting

Проблем: Бял екран / Приложението не зарежда

Причини:

Service Worker кеш е корумпиран
JavaScript грешки в конзолата
Supabase credentials са неправилни

Решение:

bash

# 1. Изчисти browser cache
# Chrome: DevTools → Application → Clear Storage → Clear site data

# 2. Unregister Service Worker
# Chrome: DevTools → Application → Service Workers → Unregister

# 3. Hard refresh
# Ctrl+Shift+R (Windows/Linux) или Cmd+Shift+R (Mac)

# 4. Провери конзолата за грешки
# F12 → Console tab

Проблем: Realtime не работи (няма автоматични обновявания)

Причини:

Realtime не е активиран за таблиците
RLS политики блокират достъпа
Network/firewall блокира WebSocket connections

Решение:

sql

-- 1. Провери дали таблиците са в publication
SELECT * FROM pg_publication_tables WHERE pubname = 'supabase_realtime';

-- 2. Добави таблиците ако липсват
ALTER PUBLICATION supabase_realtime ADD TABLE public.shipments;
ALTER PUBLICATION supabase_realtime ADD TABLE public.zones;
ALTER PUBLICATION supabase_realtime ADD TABLE public.user_roles;

-- 3. Провери RLS политики
SELECT * FROM pg_policies WHERE tablename = 'shipments';

Проблем: Push notifications не работят на iOS

Причини:

Липсват VAPID keys
Няма Edge Function за изпращане на push notifications
iOS не позволява notifications (Settings → Notifications)

Решение:

Провери дали има VAPID keys:

bash

# Провери в .env
grep VITE_WEB_PUSH_PUBLIC_KEY .env

Генерирай нови VAPID keys (виж секция VAPID Keys)
Провери дали Edge Function съществува:
bash
```
supabase functions list
```
1
iOS специфично:
- PWA трябва да е инсталиран (Add to Home Screen)
- HTTPS domain е задължителен
- Notifications трябва да са разрешени в iOS Settings

Проблем: Nginx връща 403 Forbidden

Причини:

IP адресът не е в allowlist
Nginx конфигурация е неправилна

Решение:

bash

# 1. Провери Nginx конфигурация
cat deploy/nginx.conf | grep -A 5 "allow"

# 2. Добави IP адрес в allowlist
# Редактирай deploy/nginx.conf:
#   allow YOUR_IP_ADDRESS;
#   allow 10.0.0.0/8;
#   allow 192.168.1.0/24;

# 3. Рестартирай контейнера
docker compose restart lager-guru

Проблем: Build fail в Docker

Причини:

Липсват environment variables
Node modules проблеми
Disk space

Решение:

bash

# 1. Провери .env файл
cat .env

# 2. Провери disk space
df -h

# 3. Изчисти Docker cache
docker system prune -a

# 4. Rebuild без cache
docker compose build --no-cache

# 5. Провери логове
docker compose build 2>&1 | tee build.log

Database Restore

Backup процес

bash

# 1. Настрой environment variables
export DB_HOST=your-db-host
export DB_USER=your-db-user
export DB_NAME=your-db-name
export DB_PASSWORD=your-db-password

# 2. Стартирай backup
./scripts/backup-db.sh

# 3. Провери backup файл
ls -lh backups/lager-guru/

Restore процес

bash

# 1. Намери backup файл
ls -lh backups/lager-guru/

# 2. Restore от backup
pg_restore \
  -h $DB_HOST \
  -U $DB_USER \
  -d $DB_NAME \
  --clean \
  --if-exists \
  backups/lager-guru/lager-guru-YYYYMMDD_HHMMSS.dump

# 3. Провери резултата
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT COUNT(*) FROM public.shipments;"

Point-in-Time Recovery (Supabase)

Ако използваш Supabase managed database:

Dashboard → Database → Backups
Избери backup snapshot
Restore към нов database или time point
Обнови connection string в приложението

Emergency Recovery

bash

# 1. Stop приложението
docker compose down

# 2. Restore database
pg_restore -h $DB_HOST -U $DB_USER -d $DB_NAME backup.dump

# 3. Провери миграциите
supabase migration list
supabase migration up

# 4. Restart приложението
docker compose up -d

Service Worker Cache

Изчистване на Service Worker Cache

Чрез Browser DevTools:

Отвори Chrome DevTools (F12)
Application → Service Workers
Кликни "Unregister" за всички workers
Application → Storage → Clear site data
Hard refresh (Ctrl+Shift+R)

Чрез код (ако имаш достъп):

javascript

// В browser console
navigator.serviceWorker.getRegistrations().then(function(registrations) {
  for(let registration of registrations) {
    registration.unregister();
  }
});

Force Update на Service Worker

bash

# 1. Промени version в vite.config.ts
# workbox: { ... }

# 2. Rebuild
npm run build

# 3. Redeploy
docker compose up -d --build

Проверка на кешираните файлове

bash

# В browser console
caches.keys().then(function(names) {
  for (let name of names) {
    caches.delete(name);
  }
});

VAPID Keys

Генериране на VAPID Keys

bash

# Инсталирай web-push (ако нямаш)
npm install -g web-push

# Генерирай нови keys
npx web-push generate-vapid-keys

Output:

Public Key:  [публичен ключ]
Private Key: [приватен ключ - НЕ споделяй!]

Конфигуриране на VAPID Keys

1. Frontend (.env):

bash

VITE_WEB_PUSH_PUBLIC_KEY=[публичен ключ]

2. Backend/Edge Function:

bash

# В Supabase Edge Function или backend
VAPID_PUBLIC_KEY=[публичен ключ]
VAPID_PRIVATE_KEY=[приватен ключ]
VAPID_EMAIL=mailto:admin@yourcompany.com

Проверка на VAPID Keys

bash

# Провери в .env
grep VITE_WEB_PUSH_PUBLIC_KEY .env

# Провери в build
docker compose exec lager-guru env | grep VITE_WEB_PUSH

Ротация на VAPID Keys

Важно: При ротация на keys, всички съществуващи push subscriptions трябва да се обновят!

bash

# 1. Генерирай нови keys
npx web-push generate-vapid-keys

# 2. Обнови .env файлове

# 3. Rebuild и redeploy

# 4. Изтрий стари subscriptions (ако е необходимо)
# В Supabase SQL Editor:
DELETE FROM public.push_subscriptions;

Логове

Docker Logs

bash

# Всички логове
docker compose logs -f

# Последните 100 реда
docker compose logs --tail=100

# Логове на конкретен service
docker compose logs -f lager-guru

# Логове с timestamp
docker compose logs -f -t lager-guru

Nginx Access Logs

bash

# В контейнера
docker compose exec lager-guru cat /var/log/nginx/access.log

# Или ако имаш volume mapping
tail -f /var/log/nginx/access.log

Application Logs

За frontend приложения, логовете са в browser console:

Chrome DevTools → Console
Network tab за HTTP requests
Application tab за Service Worker логове

Supabase Logs

Dashboard → Logs
- API Logs
- Auth Logs
- Realtime Logs
- Database Logs
SQL Editor → Query History
- Всички изпълнени заявки

Log Rotation

bash

# Настрой log rotation за Nginx (ако нямаш Docker logging)
# /etc/logrotate.d/nginx
/var/log/nginx/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 www-data adm
    sharedscripts
    postrotate
        [ -f /var/run/nginx.pid ] && kill -USR1 `cat /var/run/nginx.pid`
    endscript
}

Мрежов достъп

Проверка на мрежовия достъп

bash

# Провери дали порт 80 е отворен
netstat -tuln | grep :80

# Или
ss -tuln | grep :80

# Провери firewall
sudo ufw status

Настройка на firewall

bash

# Allow HTTP (порт 80)
sudo ufw allow 80/tcp

# Allow HTTPS (порт 443) - ако имаш TLS
sudo ufw allow 443/tcp

# Провери правилата
sudo ufw status verbose

Internal Network Access

bash

# Провери Nginx allowlist
cat deploy/nginx.conf | grep allow

# Тествай достъп от различни IP адреси
curl -I http://lager-guru.internal/health.html

# Провери Nginx error logs
docker compose exec lager-guru tail -f /var/log/nginx/error.log

Често срещани проблеми

Problem: "Cannot connect to Supabase"

Решение:

Провери .env файл
Провери network connectivity: curl https://your-project.supabase.co
Провери firewall rules
Провери Supabase dashboard за статус

Problem: "403 Forbidden" при достъп

Решение:

Провери IP адрес в allowlist
Провери RLS политики в Supabase
Провери user role в user_roles таблица

Problem: "Build fails with memory error"

Решение:

bash

# Увеличи Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Problem: "Docker container exits immediately"

Решение:

bash

# Провери логове
docker compose logs lager-guru

# Провери конфигурация
docker compose config

# Провери дали порт 80 е свободен
netstat -tuln | grep :80

Контакти и поддръжка

GitHub Issues: Създай issue за проблеми
Documentation: Виж README.md за пълна документация
Supabase Support: Dashboard → Support

Последна актуализация: 2025-11-05

Lager Guru - Runbook ​

Съдържание ​

Стартиране на приложението ​

Docker Deployment (Production) ​

Локална разработка ​

Проверка на състоянието ​

Health Check ​

Docker Status ​

Database Connection ​

Troubleshooting ​

Проблем: Бял екран / Приложението не зарежда ​

Проблем: Realtime не работи (няма автоматични обновявания) ​

Проблем: Push notifications не работят на iOS ​

Проблем: Nginx връща 403 Forbidden ​

Проблем: Build fail в Docker ​

Database Restore ​

Backup процес ​

Restore процес ​

Point-in-Time Recovery (Supabase) ​

Emergency Recovery ​

Service Worker Cache ​

Изчистване на Service Worker Cache ​

Force Update на Service Worker ​

Проверка на кешираните файлове ​

VAPID Keys ​

Генериране на VAPID Keys ​

Конфигуриране на VAPID Keys ​

Проверка на VAPID Keys ​

Ротация на VAPID Keys ​

Логове ​

Docker Logs ​

Nginx Access Logs ​

Application Logs ​

Supabase Logs ​

Log Rotation ​

Мрежов достъп ​

Проверка на мрежовия достъп ​

Настройка на firewall ​

Internal Network Access ​

Често срещани проблеми ​

Problem: "Cannot connect to Supabase" ​

Problem: "403 Forbidden" при достъп ​

Problem: "Build fails with memory error" ​

Problem: "Docker container exits immediately" ​

Контакти и поддръжка ​

Lager Guru - Runbook

Съдържание

Стартиране на приложението

Docker Deployment (Production)

Локална разработка

Проверка на състоянието

Health Check

Docker Status

Database Connection

Troubleshooting

Проблем: Бял екран / Приложението не зарежда

Проблем: Realtime не работи (няма автоматични обновявания)

Проблем: Push notifications не работят на iOS

Проблем: Nginx връща 403 Forbidden

Проблем: Build fail в Docker

Database Restore

Backup процес

Restore процес

Point-in-Time Recovery (Supabase)

Emergency Recovery

Service Worker Cache

Изчистване на Service Worker Cache

Force Update на Service Worker

Проверка на кешираните файлове

VAPID Keys

Генериране на VAPID Keys

Конфигуриране на VAPID Keys

Проверка на VAPID Keys

Ротация на VAPID Keys

Логове

Docker Logs

Nginx Access Logs

Application Logs

Supabase Logs

Log Rotation

Мрежов достъп

Проверка на мрежовия достъп

Настройка на firewall

Internal Network Access

Често срещани проблеми

Problem: "Cannot connect to Supabase"

Problem: "403 Forbidden" при достъп

Problem: "Build fails with memory error"

Problem: "Docker container exits immediately"

Контакти и поддръжка