kasapro

Troubleshooting

Panduan untuk mengatasi masalah umum yang mungkin terjadi saat menggunakan Kasapro.

---

Common Issues

Installation Issues

Port Already in Use

Problem: Error “port already in use” saat start services

Symptoms:

• Error message: “Bind for 0.0.0.0:9443 failed: port is already allocated”
• Services tidak bisa start

Solutions:

1. Check port usage:

   # Linux/Mac
   lsof -i :9443
   netstat -tuln | grep :9443
      
   # Windows
   netstat -ano | findstr :9443
   Get-NetTCPConnection -LocalPort 9443
   

2. Change port di .env:

   NGINX_PORT=9444
   NEXT_PUBLIC_API_URL=https://localhost:9444/api
   

3. Restart services:

   docker compose -f docker-compose.prod.yml restart
   

Docker Not Running

Problem: Error “Cannot connect to the Docker daemon”

Solutions:

• Start Docker Desktop (Windows/Mac)
• Start Docker service (Linux):

  sudo systemctl start docker
  

Out of Disk Space

Problem: Error “no space left on device”

Solutions:

1. Clean up Docker:

   docker system prune -a
   docker volume prune
   

2. Remove unused images:

   docker image prune -a
   

---

Access Issues

Cannot Access Application

Problem: Browser tidak bisa akses https://localhost:9443

Checklist:

• Services sudah running: docker compose -f docker-compose.prod.yml ps
• Port sudah benar di .env
• Browser menerima self-signed certificate
• Firewall tidak block port 9443
• Gunakan HTTPS, bukan HTTP

Solutions:

1. Check services:

   docker compose -f docker-compose.prod.yml ps
   

   Pastikan semua services status “Up”

2. Check logs:

   docker compose -f docker-compose.prod.yml logs nginx
   docker compose -f docker-compose.prod.yml logs frontend
   

3. Accept self-signed certificate:
   • Klik “Advanced” di browser
   • Klik “Proceed to localhost” atau “Accept Risk”
4. Check firewall:
   • Allow port 9443 di firewall settings

Security Warning (Self-Signed Certificate)

Problem: Browser menampilkan security warning untuk certificate

Solutions:

1. Accept untuk development (klik “Advanced” → “Proceed”)
2. Install certificate untuk production:
   • Download: https://localhost:9443/ca.crt
   • Install certificate ke browser/OS
   • Restart browser

---

Database Issues

Database Connection Error

Problem: Error “connection refused” atau “cannot connect to database”

Symptoms:

• Backend service tidak bisa connect ke database
• Error di backend logs

Solutions:

1. Check postgres service:

   docker compose -f docker-compose.prod.yml logs postgres
   docker compose -f docker-compose.prod.yml ps postgres
   

2. Check DATABASE_URL di .env:

   DATABASE_URL=postgres://pos_user:pos_pass@postgres:5432/pos_db?sslmode=disable
   

   Pastikan format sudah benar

3. Restart services:

   docker compose -f docker-compose.prod.yml restart
   

4. Recreate database (last resort):

   docker compose -f docker-compose.prod.yml down -v
   docker compose -f docker-compose.prod.yml up -d
   

Database Migration Failed

Problem: Error saat migration database

Solutions:

1. Check logs:

   docker compose -f docker-compose.prod.yml logs backend
   

2. Manual migration:
   • Check migration files
   • Manually run SQL if needed

---

Login Issues

Login Gagal

Problem: Tidak bisa login meskipun credentials sudah benar

Checklist:

• Username dan PIN sudah benar (case-sensitive)
• User status Active (bukan Inactive)
• Backend service berjalan
• Tidak ada error di console browser (F12)

Solutions:

1. Verify credentials:
   • Gunakan username dan PIN yang Anda buat saat setup wizard
   • Jika setup wizard belum dilakukan, lakukan setup terlebih dahulu (lihat Instalasi & Setup)
   • Jika setup wizard tidak muncul, default credentials sebagai fallback: kasir.demo / 1234 atau supervisor.demo / 1234 (hanya untuk kondisi tertentu)
   • Pastikan tidak ada typo (username case-sensitive)
2. Check backend logs:

   docker compose -f docker-compose.prod.yml logs backend
   

3. Check browser console (F12):
   • Lihat error messages di console
   • Check network requests
4. Reset PIN (jika perlu):
   • Edit user di Settings → Users
   • Ubah PIN
   • Simpan

Lupa PIN

Problem: Lupa PIN untuk login

Solutions:

1. Jika ada Supervisor/Owner:
   • Minta Supervisor/Owner untuk reset PIN di Settings → Users
2. Manual reset (advanced):
   • Access database
   • Reset PIN hash di tabel users
   • Atau contact support

---

Performance Issues

Application Slow

Problem: Aplikasi lambat atau tidak responsive

Solutions:

1. Check resources:
   • Check RAM usage
   • Check CPU usage
   • Check disk space
2. Restart services:

   docker compose -f docker-compose.prod.yml restart
   

3. Check database performance:

   docker compose -f docker-compose.prod.yml exec postgres psql -U pos_user -d pos_db -c "SELECT COUNT(*) FROM transactions;"
   

4. Clear browser cache:
   • Clear cache dan cookies
   • Hard refresh (Ctrl+Shift+R / Cmd+Shift+R)

---

Error Messages

Common Error Codes

400 Bad Request

Problem: Invalid request

Solutions:

• Check request format
• Check required fields
• Check browser console untuk detail error

401 Unauthorized

Problem: Not authenticated

Solutions:

• Login kembali
• Check JWT token
• Clear cookies dan login ulang

403 Forbidden

Problem: No permission

Solutions:

• Check user role
• Request permission dari Supervisor/Owner

404 Not Found

Problem: Resource not found

Solutions:

• Check URL/path
• Check apakah resource exists
• Refresh halaman

500 Internal Server Error

Problem: Server error

Solutions:

1. Check backend logs:

   docker compose -f docker-compose.prod.yml logs backend
   

2. Restart services:

   docker compose -f docker-compose.prod.yml restart
   

3. Contact support dengan error details dari logs

---

Diagnostic Tools

Health Check Endpoints

Backend Health:

curl http://localhost:8100/healthz

Expected: {"status":"ok"}

Frontend:

curl http://localhost:3100

Expected: HTML response (200 OK)

Log Viewing

View all logs:

docker compose -f docker-compose.prod.yml logs -f

View specific service:

docker compose -f docker-compose.prod.yml logs -f backend
docker compose -f docker-compose.prod.yml logs -f frontend
docker compose -f docker-compose.prod.yml logs -f postgres
docker compose -f docker-compose.prod.yml logs -f nginx

Database Inspection

Connect to database:

docker compose -f docker-compose.prod.yml exec postgres psql -U pos_user -d pos_db

Common queries:

-- Check tables
\dt

-- Check users
SELECT username, role FROM users;

-- Check products count
SELECT COUNT(*) FROM products;

-- Check transactions count
SELECT COUNT(*) FROM transactions;

---

FAQ

Q: Bagaimana cara reset password/PIN?

A:

• Supervisor/Owner bisa reset PIN di Settings → Users
• Edit user → Ubah PIN → Simpan

Q: Bagaimana cara backup database?

A:

docker compose -f docker-compose.prod.yml exec postgres pg_dump -U pos_user pos_db > backup.sql

Q: Bagaimana cara restore database?

A:

docker compose -f docker-compose.prod.yml exec -T postgres psql -U pos_user pos_db < backup.sql

Q: Bagaimana cara update aplikasi?

A:

• Pull images baru dari Docker Hub
• Restart services:

  docker compose -f docker-compose.prod.yml pull
  docker compose -f docker-compose.prod.yml up -d
  

Q: Bagaimana cara menghapus semua data?

A:

docker compose -f docker-compose.prod.yml down -v
docker compose -f docker-compose.prod.yml up -d

⚠️ Warning: Ini akan menghapus semua data!

Q: Bagaimana cara melihat logs?

A:

# All logs
docker compose -f docker-compose.prod.yml logs -f

# Specific service
docker compose -f docker-compose.prod.yml logs -f backend

---

Getting Help

GitHub Issues

Report bug atau request feature:

• GitHub Issues
• Gunakan template yang tersedia
• Sertakan error logs dan steps to reproduce

Email Support

Email: support@kasapro.app

Include:

• Description masalah
• Steps to reproduce
• Error messages
• Logs (jika ada)
• Environment (OS, Docker version)

Community

Coming Soon:

• Community forum
• Discord/Slack channel
• Documentation wiki

---

Jika masalah masih belum teratasi, jangan ragu untuk menghubungi kami!

This site is open source. Improve this page.