Lager Guru - Runbook

Operational guide for management and troubleshooting of the Lager Guru application.

Choose Language: 🇩🇪 Deutsch | 🇬🇧 English | 🇧🇬 Български

Starting the Application
Checking Status
Troubleshooting
Database Restore
Service Worker Cache
VAPID Keys
Logs
Network Access

Starting the Application

Docker Deployment (Production)

bash

# 1. Navigate to project
cd /path/to/lager-guru

# 2. Create .env file (if it doesn't exist)
cat > .env << EOF
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
EOF

# 3. Start application
docker compose up -d --build

# 4. Check status
docker compose ps
docker compose logs -f lager-guru

Local Development

bash

# 1. Install dependencies
npm install

# 2. Create .env.local file
cat > .env.local << EOF
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
EOF

# 3. Start dev server
npm run dev

# 4. Or for production preview
npm run build
npm run preview -- --host --port 8080

Checking Status

Health Check

bash

# Check health endpoint
curl http://lager-guru.internal/health.html

# Or in browser
open http://lager-guru.internal/health.html

Health endpoint checks:

✅ Static assets (HTML, CSS, JS)
✅ Supabase connection (if configured)
⚠️ Auto-refresh every 30 seconds

Docker Status

bash

# Check container status
docker compose ps

# Check logs
docker compose logs --tail=100 lager-guru

# Check resources
docker stats

Database Connection

bash

# Check Supabase connection from CLI
psql "postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres" -c "SELECT version();"

# Or via Supabase CLI
supabase status

Troubleshooting

Problem: White Screen / Application Not Loading

Causes:

Service Worker cache is corrupted
JavaScript errors in console
Supabase credentials are incorrect

Solution:

bash

# 1. Clear 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) or Cmd+Shift+R (Mac)

# 4. Check console for errors
# F12 → Console tab

Problem: Realtime Not Working (No Automatic Updates)

Causes:

Realtime is not enabled for tables
RLS policies are blocking access
Network/firewall is blocking WebSocket connections

Solution:

sql

-- 1. Check if tables are in publication
SELECT * FROM pg_publication_tables WHERE pubname = 'supabase_realtime';

-- 2. Add tables if missing
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. Check RLS policies
SELECT * FROM pg_policies WHERE tablename = 'shipments';

Problem: Push Notifications Not Working on iOS

Causes:

VAPID keys are missing
No Edge Function for sending push notifications
iOS doesn't allow notifications (Settings → Notifications)

Solution:

Check if VAPID keys exist:

bash

# Check in .env
grep VITE_WEB_PUSH_PUBLIC_KEY .env

Generate new VAPID keys (see VAPID Keys section)
Check if Edge Function exists:
bash
```
supabase functions list
```
1
iOS specific:
- PWA must be installed (Add to Home Screen)
- HTTPS domain is required
- Notifications must be enabled in iOS Settings

Problem: Nginx Returns 403 Forbidden

Causes:

IP address is not in allowlist
Nginx configuration is incorrect

Solution:

bash

# 1. Check Nginx configuration
cat deploy/nginx.conf | grep -A 5 "allow"

# 2. Add IP address to allowlist
# Edit deploy/nginx.conf:
#   allow YOUR_IP_ADDRESS;
#   allow 10.0.0.0/8;
#   allow 192.168.1.0/24;

# 3. Restart container
docker compose restart lager-guru

Problem: Build Fails in Docker

Causes:

Missing environment variables
Node modules problems
Disk space

Solution:

bash

# 1. Check .env file
cat .env

# 2. Check disk space
df -h

# 3. Clear Docker cache
docker system prune -a

# 4. Rebuild without cache
docker compose build --no-cache

# 5. Check logs
docker compose build 2>&1 | tee build.log

Database Restore

Backup Process

bash

# 1. Set 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. Start backup
./scripts/backup-db.sh

# 3. Check backup file
ls -lh backups/lager-guru/

Restore Process

bash

# 1. Find backup file
ls -lh backups/lager-guru/

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

# 3. Check result
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT COUNT(*) FROM public.shipments;"

Point-in-Time Recovery (Supabase)

If using Supabase managed database:

Dashboard → Database → Backups
Select backup snapshot
Restore to new database or time point
Update connection string in application

Emergency Recovery

bash

# 1. Stop application
docker compose down

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

# 3. Check migrations
supabase migration list
supabase migration up

# 4. Restart application
docker compose up -d

Service Worker Cache

Clearing Service Worker Cache

Via Browser DevTools:

Open Chrome DevTools (F12)
Application → Service Workers
Click "Unregister" for all workers
Application → Storage → Clear site data
Hard refresh (Ctrl+Shift+R)

Via Code (if you have access):

javascript

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

Force Update Service Worker

bash

# 1. Change version in vite.config.ts
# workbox: { ... }

# 2. Rebuild
npm run build

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

Checking Cached Files

bash

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

VAPID Keys

Generating VAPID Keys

bash

# Install web-push (if you don't have it)
npm install -g web-push

# Generate new keys
npx web-push generate-vapid-keys

Output:

Public Key:  [public key]
Private Key: [private key - DO NOT share!]

Configuring VAPID Keys

1. Frontend (.env):

bash

VITE_WEB_PUSH_PUBLIC_KEY=[public key]

2. Backend/Edge Function:

bash

# In Supabase Edge Function or backend
VAPID_PUBLIC_KEY=[public key]
VAPID_PRIVATE_KEY=[private key]
VAPID_EMAIL=mailto:admin@yourcompany.com

Checking VAPID Keys

bash

# Check in .env
grep VITE_WEB_PUSH_PUBLIC_KEY .env

# Check in build
docker compose exec lager-guru env | grep VITE_WEB_PUSH

Rotating VAPID Keys

Important: When rotating keys, all existing push subscriptions must be updated!

bash

# 1. Generate new keys
npx web-push generate-vapid-keys

# 2. Update .env files

# 3. Rebuild and redeploy

# 4. Delete old subscriptions (if necessary)
# In Supabase SQL Editor:
DELETE FROM public.push_subscriptions;

Logs

Docker Logs

bash

# All logs
docker compose logs -f

# Last 100 lines
docker compose logs --tail=100

# Logs for specific service
docker compose logs -f lager-guru

# Logs with timestamp
docker compose logs -f -t lager-guru

Nginx Access Logs

bash

# In container
docker compose exec lager-guru cat /var/log/nginx/access.log

# Or if volume mapping exists
tail -f /var/log/nginx/access.log

Application Logs

For frontend applications, logs are in browser console:

Chrome DevTools → Console
Network tab for HTTP requests
Application tab for Service Worker logs

Supabase Logs

Dashboard → Logs
- API Logs
- Auth Logs
- Realtime Logs
- Database Logs
SQL Editor → Query History
- All executed queries

Log Rotation

bash

# Set up log rotation for Nginx (if no 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
}

Network Access

Checking Network Access

bash

# Check if port 80 is open
netstat -tuln | grep :80

# Or
ss -tuln | grep :80

# Check firewall
sudo ufw status

Configuring Firewall

bash

# Allow HTTP (port 80)
sudo ufw allow 80/tcp

# Allow HTTPS (port 443) - if TLS exists
sudo ufw allow 443/tcp

# Check rules
sudo ufw status verbose

Internal Network Access

bash

# Check Nginx allowlist
cat deploy/nginx.conf | grep allow

# Test access from different IP addresses
curl -I http://lager-guru.internal/health.html

# Check Nginx error logs
docker compose exec lager-guru tail -f /var/log/nginx/error.log

Common Problems

Problem: "Cannot connect to Supabase"

Solution:

Check .env file
Check network connectivity: curl https://your-project.supabase.co
Check firewall rules
Check Supabase dashboard for status

Problem: "403 Forbidden" on access

Solution:

Check IP address in allowlist
Check RLS policies in Supabase
Check user role in user_roles table

Problem: "Build fails with memory error"

Solution:

bash

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Problem: "Docker container exits immediately"

Solution:

bash

# Check logs
docker compose logs lager-guru

# Check configuration
docker compose config

# Check if port 80 is free
netstat -tuln | grep :80

Contacts and Support

GitHub Issues: Create issue for problems
Documentation: See README.md for complete documentation
Supabase Support: Dashboard → Support

Last Updated: 2025-11-05

Lager Guru - Runbook ​

Table of Contents ​

Starting the Application ​

Docker Deployment (Production) ​

Local Development ​

Checking Status ​

Health Check ​

Docker Status ​

Database Connection ​

Troubleshooting ​

Problem: White Screen / Application Not Loading ​

Problem: Realtime Not Working (No Automatic Updates) ​

Problem: Push Notifications Not Working on iOS ​

Problem: Nginx Returns 403 Forbidden ​

Problem: Build Fails in Docker ​

Database Restore ​

Backup Process ​

Restore Process ​

Point-in-Time Recovery (Supabase) ​

Emergency Recovery ​

Service Worker Cache ​

Clearing Service Worker Cache ​

Force Update Service Worker ​

Checking Cached Files ​

VAPID Keys ​

Generating VAPID Keys ​

Configuring VAPID Keys ​

Checking VAPID Keys ​

Rotating VAPID Keys ​

Logs ​

Docker Logs ​

Nginx Access Logs ​

Application Logs ​

Supabase Logs ​

Log Rotation ​

Network Access ​

Checking Network Access ​

Configuring Firewall ​

Internal Network Access ​

Common Problems ​

Problem: "Cannot connect to Supabase" ​

Problem: "403 Forbidden" on access ​

Problem: "Build fails with memory error" ​

Problem: "Docker container exits immediately" ​

Contacts and Support ​

Lager Guru - Runbook

Table of Contents

Starting the Application

Docker Deployment (Production)

Local Development

Checking Status

Health Check

Docker Status

Database Connection

Troubleshooting

Problem: White Screen / Application Not Loading

Problem: Realtime Not Working (No Automatic Updates)

Problem: Push Notifications Not Working on iOS

Problem: Nginx Returns 403 Forbidden

Problem: Build Fails in Docker

Database Restore

Backup Process

Restore Process

Point-in-Time Recovery (Supabase)

Emergency Recovery

Service Worker Cache

Clearing Service Worker Cache

Force Update Service Worker

Checking Cached Files

VAPID Keys

Generating VAPID Keys

Configuring VAPID Keys

Checking VAPID Keys

Rotating VAPID Keys

Logs

Docker Logs

Nginx Access Logs

Application Logs

Supabase Logs

Log Rotation

Network Access

Checking Network Access

Configuring Firewall

Internal Network Access

Common Problems

Problem: "Cannot connect to Supabase"

Problem: "403 Forbidden" on access

Problem: "Build fails with memory error"

Problem: "Docker container exits immediately"

Contacts and Support