kasapro

Instalasi & Setup Kasapro

Panduan lengkap untuk menginstal Kasapro di komputer Anda menggunakan Docker images yang sudah siap pakai.

---

Apa yang Anda Butuhkan?

Komputer/Server

Minimum:

• Windows 10+, macOS 10.15+, atau Linux
• RAM 4GB (8GB lebih baik untuk performa optimal)
• Ruang disk 2GB (untuk aplikasi dan data)
• Processor 2-core (4-core lebih baik)

Recommended:

• RAM 8GB atau lebih
• Ruang disk 10GB+ (untuk data dan backups)
• Processor 4-core atau lebih

💡 Tips: Komputer/laptop yang Anda pakai sehari-hari biasanya sudah cukup. Tidak perlu server khusus!

Software

Yang Anda Butuhkan:

• Docker Desktop (gratis)

Docker adalah software yang memungkinkan aplikasi berjalan di “container” terisolasi. Ini membuat instalasi Kasapro menjadi lebih mudah karena tidak perlu install banyak dependencies manual.

---

Langkah 1: Install Docker (5 menit)

Untuk Windows/Mac

1. Download Docker Desktop:
   • Buka docker.com/products/docker-desktop
   • Klik “Download for Windows” atau “Download for Mac”
   • File download akan mulai
2. Install Docker Desktop:
   • Buka file yang sudah didownload
   • Ikuti instruksi installer (Next, Next, Install)
   • Setelah install selesai, restart komputer jika diminta
3. Buka Docker Desktop:
   • Setelah restart, buka Docker Desktop dari Start Menu (Windows) atau Applications (Mac)
   • Tunggu hingga Docker Desktop siap (icon akan berubah hijau)
   • Icon Docker di taskbar (Windows) atau menu bar (Mac) menunjukkan status

Untuk Linux

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Tambahkan user ke group docker (opsional, untuk tidak perlu sudo)
sudo usermod -aG docker $USER

# Verifikasi install
docker --version
docker compose version

⚠️ Catatan: Setelah install Docker, logout dan login lagi agar group docker aktif.

Verifikasi Docker

Buka terminal/command prompt dan ketik:

docker --version
docker compose version

Jika muncul versi Docker, berarti instalasi berhasil! ✅

---

Langkah 2: Download Files yang Diperlukan (2 menit)

Anda perlu 2 file untuk menjalankan Kasapro:

1. docker-compose.prod.yml - File konfigurasi untuk menjalankan aplikasi
2. .env.example - File contoh untuk environment variables

Option A: Download dari GitHub (Recommended)

1. Buka repository Kasapro:
   • GitHub Repository
2. Download files:
   • Download docker-compose.prod.yml
   • Download .env.example (atau .env.prod.example)
3. Simpan di folder yang mudah diakses:
   • Buat folder baru (contoh: C:\kasapro atau ~/kasapro)
   • Simpan kedua file tersebut di folder tersebut

Option B: Clone Repository (Jika Anda Familiar dengan Git)

git clone https://github.com/sofyan-solutions/kasapro.git
cd kasapro

---

Langkah 3: Setup Environment File (1 menit)

Buat file .env dari .env.example:

# Windows (Command Prompt)
copy .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env

# Mac/Linux
cp .env.example .env

File .env sudah memiliki default settings yang bisa langsung digunakan!

Anda tidak perlu mengubah apapun di file ini untuk pertama kali, kecuali jika:

• Port 9443 sudah digunakan aplikasi lain (sangat jarang)
• Anda ingin menggunakan port lain

💡 Tips: Default settings sudah optimal untuk kebanyakan penggunaan. Tidak perlu diubah jika tidak yakin.

---

Langkah 4: Pull Docker Images (3-5 menit)

Docker images adalah “paket” aplikasi Kasapro yang sudah siap pakai. Anda perlu mendownload-nya dari Docker Hub.

Set Environment Variables

Windows (Command Prompt):

set DOCKER_IMAGE_PREFIX=sofyansolutions/kasapro
set ERP_VERSION=v1.0.0

Windows (PowerShell):

$env:DOCKER_IMAGE_PREFIX="sofyansolutions/kasapro"
$env:ERP_VERSION="v1.0.0"

Mac/Linux:

export DOCKER_IMAGE_PREFIX=sofyansolutions/kasapro
export ERP_VERSION=v1.0.0

Pull Images

Option 1: Pull Manual (Lebih Kontrol)

docker pull sofyansolutions/kasapro-backend:v1.0.0
docker pull sofyansolutions/kasapro-frontend:v1.0.0
docker pull sofyansolutions/kasapro-nginx:v1.0.0

Option 2: Pull Otomatis dengan Docker Compose (Lebih Mudah)

docker compose -f docker-compose.prod.yml --env-file .env pull

⏱️ Waktu: Pull images memakan waktu sekitar 3-5 menit tergantung kecepatan internet. Ini hanya dilakukan sekali di awal.

---

Langkah 5: Jalankan Aplikasi (1 menit)

Start aplikasi:

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

Apa yang terjadi:

• Docker akan membuat container untuk backend, frontend, database, dan nginx
• Aplikasi akan mulai running di background
• Tunggu sekitar 30-60 detik untuk semua service siap

Cek status:

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

Pastikan semua service status “Up” dan healthy. Jika ada yang masih “starting”, tunggu beberapa detik lagi.

---

Langkah 6: Akses Aplikasi (30 detik)

Buka browser (Chrome, Firefox, Edge, Safari) dan akses:

https://localhost:9443

⚠️ Penting: Gunakan HTTPS, bukan HTTP!

Security Warning (Normal!)

Browser Anda mungkin menampilkan peringatan security karena menggunakan self-signed certificate. Ini normal untuk aplikasi self-hosted.

Cara mengatasinya:

Chrome/Edge:

1. Klik “Advanced” atau “Lanjutkan ke localhost (tidak aman)”
2. Aplikasi akan terbuka

Firefox:

1. Klik “Advanced”
2. Klik “Accept the Risk and Continue”

Safari:

1. Klik “Show Details”
2. Klik “visit this website”

💡 Tips: Jika ingin menghilangkan warning ini, Anda bisa install certificate. Lihat Konfigurasi Lanjutan untuk detail.

---

Langkah 7: Setup Awal dengan Setup Wizard (2-3 menit)

Setup Wizard Otomatis

Setelah aplikasi terbuka untuk pertama kali, Setup Wizard akan muncul otomatis di halaman utama. Setup wizard memandu Anda untuk melakukan konfigurasi awal dengan mudah.

Step 1: Informasi Toko

Isi informasi toko Anda:

1. Nama Organisasi - Nama bisnis/organisasi Anda (contoh: “Toko Sembako Pak Budi”)
2. Nama Toko - Nama toko yang akan muncul di struk (bisa sama dengan nama organisasi)
3. Alamat Toko - Alamat lengkap toko (opsional, tapi recommended)
4. Telepon - Nomor telepon toko (opsional)

💡 Tips: Informasi ini akan muncul di struk transaksi, jadi pastikan sudah benar.

Klik “Lanjutkan” untuk melanjutkan ke step berikutnya.

Step 2: Buat Akun Admin

Buat akun admin untuk akses sistem:

1. Username - Username untuk login (contoh: admin, pemilik, atau nama Anda)
   • ⚠️ Username harus unik, tidak boleh duplikat
   • Gunakan huruf kecil, angka, dan underscore/hyphen
2. Nama Lengkap - Nama lengkap Anda (contoh: “Budi Santoso”)
   • Ini akan muncul di laporan dan audit logs
3. PIN - PIN minimal 4 digit (contoh: 1234, 5678, atau kombinasi yang mudah diingat)
   • ⚠️ Penting: Gunakan PIN yang mudah diingat tapi tetap aman!
   • Jangan gunakan PIN yang terlalu mudah ditebak (contoh: 0000, 1111)

⚠️ Penting: Ingat username dan PIN Anda! Anda akan menggunakannya untuk login setiap hari. Simpan informasi ini di tempat yang aman.

Klik “Lanjutkan” untuk melanjutkan ke step berikutnya.

Step 3: Selesai

Setelah semua informasi diisi, klik “Selesai” untuk menyelesaikan setup.

Setelah setup selesai:

• Setup wizard akan menutup
• Anda akan diarahkan ke halaman login
• Login dengan akun admin yang baru saja Anda buat
• Kredensial default (kasir.demo/1234) akan otomatis dinonaktifkan untuk keamanan

✅ Penting: Setup wizard hanya muncul sekali saat pertama kali install. Pastikan semua informasi sudah benar sebelum klik “Selesai”.

---

Jika Setup Wizard Tidak Muncul (Fallback - Sangat Jarang)

Jika setup wizard tidak muncul (misalnya karena sudah pernah di-setup sebelumnya, atau ada masalah teknis), Anda bisa login dengan kredensial default:

1. Buka halaman login di https://localhost:9443/login
2. Gunakan kredensial default:
   • Username: kasir.demo atau supervisor.demo
   • PIN: 1234
3. Klik “Masuk”

⚠️ Peringatan Keamanan: Setelah login dengan default credentials:

1. Segera buat user admin baru di Settings → Users
2. Ganti PIN default atau nonaktifkan user default
3. Jangan gunakan default credentials di production!

---

Verifikasi Instalasi

Checklist Instalasi Berhasil

• Docker Desktop sudah running
• Semua services status “Up” (cek dengan docker compose ps)
• Bisa akses aplikasi di https://localhost:9443
• Bisa login dengan kredensial default atau user yang sudah dibuat
• Dashboard muncul setelah login
• Tidak ada error di halaman

Test Fitur Dasar

1. Coba buka halaman POS - Harus muncul interface kasir
2. Coba buka halaman Produk - Harus muncul daftar produk (kosong untuk pertama kali)
3. Coba buka Dashboard - Harus muncul dashboard dengan KPI cards

Jika semua berhasil, berarti instalasi sudah berhasil! 🎉

---

Troubleshooting Instalasi

Docker Tidak Running

Problem: Error “Cannot connect to Docker daemon”

Solution:

• Pastikan Docker Desktop sudah dibuka
• Tunggu hingga Docker Desktop fully started (icon hijau)
• Restart Docker Desktop jika perlu

Port Sudah Digunakan

Problem: Error “port already in use”

Solution:

1. Ubah port di file .env:

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

2. Restart services:

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

Tidak Bisa Akses Aplikasi

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

Checklist:

• Services sudah running? (cek dengan docker compose ps)
• Menggunakan HTTPS, bukan HTTP?
• Browser sudah accept security warning?
• Firewall tidak block port 9443?

Database Error

Problem: Error connecting to database

Solution:

1. Restart semua services:

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

2. Tunggu 30-60 detik untuk database ready
3. Coba akses lagi

📚 Butuh bantuan lebih? Lihat Troubleshooting Guide untuk solusi masalah umum lainnya.

---

Langkah Selanjutnya

Setelah instalasi berhasil:

1. ✅ Quick Start Guide - Mulai menggunakan dalam 5 menit
2. ✅ Fitur-Fitur Aplikasi - Pelajari semua fitur yang tersedia
3. ✅ Panduan Penggunaan - Panduan detail untuk setiap fitur

---

Tips & Best Practices

1. Backup Data Secara Berkala

Setup backup otomatis atau manual untuk data Anda. Lihat Konfigurasi - Backup untuk detail.

2. Update Aplikasi Secara Berkala

Update aplikasi untuk mendapatkan fitur baru dan bug fixes:

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

3. Monitor Resources

Pastikan komputer Anda punya resources cukup (RAM, disk space). Monitor secara berkala.

4. Keep Docker Desktop Running

Jangan tutup Docker Desktop saat menggunakan Kasapro. Aplikasi berjalan di dalam Docker containers.

---

Selamat! Kasapro sudah terinstal dan siap digunakan! 🎉

Jika ada pertanyaan atau masalah, jangan ragu untuk menghubungi kami di support@kasapro.app atau lihat Troubleshooting Guide.

This site is open source. Improve this page.