kasapro

Konfigurasi

Panduan lengkap untuk mengkonfigurasi Kasapro sesuai kebutuhan Anda.

---

Environment Variables

Backend Configuration

File: .env atau environment variables

Database:

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

Redis:

REDIS_URL=redis://redis:6379/0

JWT Configuration:

JWT_ACCESS_SECRET=your-access-secret-min-32-chars
JWT_REFRESH_SECRET=your-refresh-secret-min-32-chars
JWT_ACCESS_TTL=15m
JWT_REFRESH_TTL=168h
JWT_ISSUER=kasapro-backend
JWT_AUDIENCE=kasapro-frontend

CORS:

CORS_ALLOW_ORIGIN=https://localhost

Deployment Model:

DEPLOYMENT_MODEL=self-hosted

⚠️ Security Note: Generate secure secrets untuk production:

openssl rand -base64 32

Frontend Configuration

API URL:

NEXT_PUBLIC_API_URL=https://localhost:9443/api

Telemetry:

NEXT_TELEMETRY_DISABLED=1

---

Port Configuration

Default Ports

Service	Default Port	Description
Backend API	8100	Go backend API server
Frontend Web	3100	Next.js frontend server
Nginx HTTPS	9443	Reverse proxy with SSL
PostgreSQL	5544	Database server (external)
Redis	6381	Cache server (external)

Mengubah Port

Edit file .env:

BACKEND_PORT=8101          # Jika 8100 sudah digunakan
FRONTEND_PORT=3101         # Jika 3100 sudah digunakan
NGINX_PORT=9444            # Jika 9443 sudah digunakan
POSTGRES_PORT=5545         # Jika 5544 sudah digunakan
REDIS_PORT=6382            # Jika 6381 sudah digunakan

Jangan lupa update API URL jika mengubah NGINX_PORT:

NEXT_PUBLIC_API_URL=https://localhost:9444/api

Restart services setelah mengubah port:

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

Check Port Availability

Linux/Mac:

./scripts/check-ports.sh

Windows:

.\scripts\check-ports.ps1

Manual Check:

Linux/Mac:

# Check port 9443
netstat -tuln | grep :9443
lsof -i :9443

# Check port 8100
netstat -tuln | grep :8100
lsof -i :8100

Windows (PowerShell):

# Check port 9443
netstat -an | findstr :9443
Get-NetTCPConnection -LocalPort 9443

# Check port 8100
netstat -an | findstr :8100
Get-NetTCPConnection -LocalPort 8100

Troubleshooting Port Conflicts

Problem: Port Already in Use

Jika port sudah digunakan aplikasi lain:

1. Identifikasi aplikasi yang menggunakan port:

   Linux/Mac:

   lsof -i :9443
   # Output akan menunjukkan PID dan aplikasi
   

   Windows:

   Get-NetTCPConnection -LocalPort 9443 | Select-Object OwningProcess
   Get-Process -Id <PID> | Select-Object ProcessName
   

2. Solusi:

   Option 1: Stop aplikasi yang menggunakan port

   • Stop aplikasi yang menggunakan port tersebut
   • Atau restart komputer untuk release semua port

   Option 2: Gunakan port lain (Recommended)

   • Edit file .env dengan port yang berbeda
   • Pastikan port baru tidak digunakan
   • Restart services

Problem: Cannot Access Application After Changing Port

1. Pastikan API URL sudah diupdate:

   # Jika NGINX_PORT diubah ke 9444
   NEXT_PUBLIC_API_URL=https://localhost:9444/api
   

2. Restart semua services:

   docker compose -f docker-compose.prod.yml down
   docker compose -f docker-compose.prod.yml --env-file .env up -d
   

3. Clear browser cache dan akses dengan port baru

Problem: Port Changed But Still Using Old Port

1. Pastikan menggunakan file .env yang benar:

   # Verify environment file
   cat .env | grep PORT
   

2. Pastikan environment variables sudah di-set:

   # Check if variables are loaded
   docker compose -f docker-compose.prod.yml config | grep -i port
   

3. Restart services dengan explicit env file:

   docker compose -f docker-compose.prod.yml --env-file .env up -d
   

---

Store Configuration

Store Information

Di aplikasi:

1. Klik menu “Settings” → “Store” atau “Toko”
2. Edit informasi toko:
   • Nama Organisasi
   • Nama Toko
   • Alamat Toko
   • Telepon
   • Email (opsional)

Informasi ini akan muncul di:

• Receipt
• Reports
• Dashboard

Receipt Customization

Coming Soon:

• Custom receipt template
• Logo toko di receipt
• Footer message di receipt

---

Performance Tuning

Database Optimization

PostgreSQL Configuration:

Edit docker-compose.prod.yml untuk postgres service:

postgres:
  environment:
    - POSTGRES_SHARED_BUFFERS=256MB
    - POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
    - POSTGRES_MAINTENANCE_WORK_MEM=64MB

Index Optimization:

• Indexes sudah di-set untuk performance optimal
• Monitor slow queries via PostgreSQL logs

Caching Configuration

Redis Configuration:

Redis digunakan untuk:

• Session caching
• Rate limiting
• Temporary data storage

Default Redis:

• Max memory: 256MB
• Eviction policy: allkeys-lru

Custom Redis Config: Edit docker-compose.prod.yml untuk redis service:

redis:
  command: redis-server --maxmemory 512mb --maxmemory-policy allkeys-lru

---

Backup Configuration

Backup Strategy

Manual Backup:

1. Database Backup:

# Backup database
docker compose -f docker-compose.prod.yml exec postgres pg_dump -U pos_user pos_db > backup_$(date +%Y%m%d_%H%M%S).sql

# Restore database
docker compose -f docker-compose.prod.yml exec -T postgres psql -U pos_user pos_db < backup_20250101_120000.sql

2. Volume Backup:

# Backup volumes
docker run --rm -v kasapro_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_data_backup.tar.gz /data

Automated Backup (Recommended)

Setup cron job untuk automated backup:

Linux/Mac:

# Edit crontab
crontab -e

# Add daily backup at 2 AM
0 2 * * * cd /path/to/kasapro && docker compose -f docker-compose.prod.yml exec -T postgres pg_dump -U pos_user pos_db > backups/backup_$(date +\%Y\%m\%d).sql

Windows:

• Use Task Scheduler untuk scheduled backup
• Atau gunakan third-party backup tools

Restore Procedures

1. Restore Database:

# Stop services
docker compose -f docker-compose.prod.yml down

# Restore database
docker compose -f docker-compose.prod.yml up -d postgres
docker compose -f docker-compose.prod.yml exec -T postgres psql -U pos_user pos_db < backup_file.sql

# Start services
docker compose -f docker-compose.prod.yml up -d

2. Restore Volumes:

# Stop services
docker compose -f docker-compose.prod.yml down

# Restore volumes
docker run --rm -v kasapro_postgres_data:/data -v $(pwd):/backup alpine tar xzf /backup/postgres_data_backup.tar.gz -C /

# Start services
docker compose -f docker-compose.prod.yml up -d

---

Security Configuration

SSL/HTTPS

Self-Signed Certificate (Default):

• Certificate otomatis di-generate saat pertama kali start
• Certificate tersimpan di volume: ./infra/nginx/ssl/

Custom Certificate:

1. Letakkan certificate files di ./infra/nginx/ssl/:
   • cert.pem - Certificate file
   • key.pem - Private key file
2. Update nginx config jika perlu (advanced)

Trust Self-Signed Certificate:

1. Download CA certificate: https://localhost:9443/ca.crt
2. Install certificate ke browser/OS
3. Restart browser

JWT Secrets

Generate Secure Secrets:

# Linux/Mac
openssl rand -base64 32

# Windows PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }))

Update di .env:

JWT_ACCESS_SECRET=generated-secret-here
JWT_REFRESH_SECRET=generated-secret-here

Database Security

Change Default Credentials:

1. Edit .env:

   POSTGRES_USER=your_secure_username
   POSTGRES_PASSWORD=your_secure_password
   DATABASE_URL=postgres://your_secure_username:your_secure_password@postgres:5432/pos_db?sslmode=disable
   

2. Restart services:

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

---

Feature Flags (Coming Soon)

Feature flags akan tersedia di future versions untuk enable/disable fitur tertentu.

---

Logging Configuration

Application Logs

View Logs:

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

# 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

Log Levels

Backend:

• Default: INFO
• Set via LOG_LEVEL environment variable (DEBUG, INFO, WARN, ERROR)

Frontend:

• Logs di browser console (F12)
• Production: Errors only

---

Network Configuration

Firewall Rules

Required Ports:

• 9443 (HTTPS) - Must be open untuk akses aplikasi
• 8100 (Backend) - Optional, untuk direct API access
• 3100 (Frontend) - Optional, untuk direct frontend access

Internal Ports (tidak perlu expose):

• 5432 (PostgreSQL internal)
• 6379 (Redis internal)

Reverse Proxy Setup

Jika menggunakan reverse proxy eksternal (Nginx, Apache):

1. Setup reverse proxy untuk forward ke https://localhost:9443
2. Configure SSL di reverse proxy
3. Update CORS_ALLOW_ORIGIN di backend environment

---

Monitoring (Coming Soon)

Monitoring features akan tersedia di future versions:

• Health check endpoints
• Metrics collection
• Alerting

---

Advanced Configuration

Custom Nginx Config

Edit nginx config:

• File: ./infra/nginx/nginx.conf
• Restart nginx service setelah perubahan

Custom Database Config

Edit PostgreSQL config:

• File: postgresql.conf (via volume mount)
• Restart postgres service setelah perubahan

---

Next Steps:

• Troubleshooting - Common issues dan solusi
• Arsitektur Teknis - Memahami sistem

This site is open source. Improve this page.