Dokumentasi

Pasang dan pakai Invoisan

Name: Invoisan
Brand: Invoisan

Dari nol sampai invoice pertama terkirim: pilih cara pemasangan, siapkan database, buat akun admin, lalu ikuti panduan tiap fiturnya.

Mulai instalasi Cara pakai fitur Solusi masalah

Instalasi & Setup

Invoisan berjalan di PHP 8.2 + MySQL, dan tersedia dua jalur pemasangan: Docker Compose (paling cepat, satu perintah) atau shared hosting/cPanel (tanpa Docker). Keduanya memakai database yang sama, jadi kamu bisa pindah kapan saja.

PHP 8.2+ekstensi intl, mbstring, mysqli, gd

MySQL 8 / MariaDB 10.6+user khusus, bukan root

writable/ bisa ditulissession, cache, log, upload logo

Tidak ada halaman installer. Kredensial database ditulis di file .env (atau lewat environment Docker), lalu skema diimpor sekali dari database/schema.sql. Setelah itu akun admin pertama dibuat dengan seeder. Semua langkah di bawah sudah urut, tinggal ikuti.

Docker ComposePaling cepat

Satu perintah menyalakan tiga container: nginx, PHP-FPM, dan MySQL. Skema database diimpor otomatis saat volume pertama kali dibuat, jadi tidak perlu phpMyAdmin.

Shared HostingTanpa Docker

Cocok kalau kamu sudah punya paket hosting PHP. Tidak perlu Docker; cukup File Manager, phpMyAdmin, dan Terminal cPanel (kalau tersedia) untuk menjalankan seeder.

VPS dengan Docker Compose

Satu perintah menyalakan tiga container: nginx, PHP-FPM, dan MySQL. Skema database diimpor otomatis saat volume pertama kali dibuat, jadi tidak perlu phpMyAdmin.

Siapkan file environment

Masuk ke server, letakkan folder aplikasi di direktori kerja (misal /var/www/invoisan), lalu buat file .env.compose berisi port dan kredensial database.

File ini yang dibaca Docker Compose. Jangan dicampur dengan file env milik CodeIgniter — Compose tidak bisa memparse formatnya.

Buat .env.compose

APP_PORT=8080
APP_BASEURL=http://localhost:8080/
DB_NAME=invoisan
DB_USER=invoisan_user
DB_PASSWORD=ganti-password-kuat
DB_ROOT_PASSWORD=ganti-juga-ini
CI_ENVIRONMENT=production
TZ=Asia/Jakarta

Port database sengaja hanya di-bind ke 127.0.0.1 (default 3307), jadi tidak bisa diakses dari luar server.

Buat .env aplikasi

Salin file env bawaan repo, lalu sesuaikan baseURL, kredensial database (harus sama dengan .env.compose), dan encryption.key.

Terminal

cp env .env
openssl rand -hex 32   # tempel hasilnya ke encryption.key

# contoh isi .env
app.baseURL = 'http://localhost:8080/'
database.default.hostname = db
database.default.database = invoisan
database.default.username = invoisan_user
database.default.password = ganti-password-kuat
encryption.key = hex2bin:<64 karakter hex>

Di dalam Docker, hostname database adalah nama service-nya yaitu db. Kalau pakai MySQL di host yang sama (VPS native), ganti jadi 127.0.0.1.

Build dan nyalakan

Selalu jalankan Compose dengan --env-file supaya file .env.compose yang dipakai. Build pertama mengunduh image dan meng-compile asset, jadi butuh beberapa menit.

Terminal

docker compose --env-file .env.compose up -d --build
docker compose --env-file .env.compose ps

Bind mount menutupi folder vendor/ di dalam image. compose.yaml sudah menyiasatinya dengan volume anonim /var/www/html/vendor — jangan dihapus, kalau tidak semua request jadi 500.

Buat akun administrator

Setelah container sehat, buat admin pertama. Ada dua pilihan: akun bersih tanpa data contoh, atau data demo lengkap untuk mencoba tampilan.

Akun bersih

docker compose --env-file .env.compose exec \
  -e ADMIN_NAME="Nama Kamu" \
  -e ADMIN_EMAIL=owner@example.com \
  -e ADMIN_PASSWORD='password-kuat-8karakter' \
  app php spark db:seed AdminSeeder

Mau lihat versi demo? Jalankan php spark db:seed InitialSeeder — isinya admin, staff, 7 client, 5 produk, dan belasan invoice contoh. Jangan dipakai di produksi.

Shared Hosting / cPanel

Cocok kalau kamu sudah punya paket hosting PHP. Tidak perlu Docker; cukup File Manager, phpMyAdmin, dan Terminal cPanel (kalau tersedia) untuk menjalankan seeder.

Unggah file & arahkan document root

Ekstrak arsip aplikasi di luar public_html, lalu arahkan domain/subdomain ke folder public/. Struktur folder memisahkan kode dari area yang boleh diakses browser.

Struktur folder

invoisan/
├── app/          ← kode aplikasi (jangan diekspos)
├── public/       ← document root mengarah ke SINI
│   └── index.php
├── vendor/       ← dependency composer
├── writable/     ← session, cache, log, upload
└── .env          ← kredensial database

Kalau hosting tidak mengizinkan ubah document root, lihat Hosting tidak bisa mengubah document root.

Buat database & impor skema

Di cPanel → MySQL Databases, buat database dan user khusus, lalu beri akses penuh. Setelah itu buka phpMyAdmin, pilih database tadi, dan impor database/schema.sql.

Skema hanya berisi struktur tabel dan tiga template desain bawaan — belum ada user. Akun admin dibuat di langkah berikutnya.

Jangan pakai user root hosting. Buat user khusus per aplikasi supaya risikonya terbatas kalau password bocor.

Isi .env

Salin file env menjadi .env di root aplikasi, lalu isi kredensial database dan baseURL sesuai domain. Akhiri baseURL dengan garis miring.

.env

CI_ENVIRONMENT = production
app.baseURL = 'https://invoice.domainmu.id/'
app.appTimezone = 'Asia/Jakarta'

database.default.hostname = localhost
database.default.database = cpuser_invoisan
database.default.username = cpuser_invoice
database.default.password = password-database
database.default.DBDriver = MySQLi
database.default.port = 3306

encryption.key = hex2bin:<64 karakter hex>

Set permission writable/ ke 775 (atau 755 kalau hostingnya ketat). Folder ini dipakai untuk session, cache, log, dan logo perusahaan.

Buat admin pertama

Kalau cPanel menyediakan Terminal, jalankan seeder dari root aplikasi. Kalau tidak ada Terminal, minta hosting mengaktifkannya atau gunakan paket Enterprise yang sudah termasuk bantuan instalasi.

Terminal cPanel

cd ~/invoisan
ADMIN_NAME="Nama Kamu" \
ADMIN_EMAIL=owner@example.com \
ADMIN_PASSWORD='password-kuat-8karakter' \
php spark db:seed AdminSeeder

Seeder otomatis berhenti kalau tabel users sudah berisi data. Kosongkan dulu tabelnya kalau kamu perlu membuat ulang akun.

Setelah terpasang: login pertama

Dua hal yang paling sering terlupa setelah instalasi: mengganti password bawaan dan mengisi identitas perusahaan. Keduanya menentukan isi invoice yang dikirim ke client.

Masuk dan ganti password

Buka domain aplikasi, masuk dengan email dan password yang kamu set saat seeding. Setelah masuk, buka menu profil di kanan atas untuk mengganti password.

Ada dua role: admin melihat semua menu, staff tidak melihat Templates, Users, dan Settings.

Dashboard Invoisan setelah login pertama

Dashboard setelah login: ringkasan tagihan, grafik enam bulan, dan status invoice.

Isi identitas perusahaan

Menu Settings → Profil Perusahaan. Nama, alamat, email, telepon, website, NPWP, dan rekening bank di sini yang tercetak di setiap invoice. Upload logo kalau mau header invoice memakai logo sendiri (PNG/JPG/WebP maksimal 2 MB).

Logo tampil di header invoice, bisa dimatikan per template.
NPWP bisa disembunyikan kalau tidak diperlukan.
Rekening bank mendukung beberapa baris — satu baris satu rekening.

Halaman Settings Invoisan untuk identitas perusahaan

Settings → Profil Perusahaan: identitas, logo, dan instruksi pembayaran.

Pemakaian

Cara memakai setiap fitur

Urutannya mengikuti alur kerja harian: lihat dashboard, buat invoice, simpan client dan produk, atur template, lalu kirim ke client lewat PDF, WhatsApp, atau link publik.

Dashboard

/dashboard

Ringkasan kondisi tagihan: total outstanding, pendapatan bulan berjalan, yang lewat jatuh tempo, grafik enam bulan terakhir, dan distribusi status invoice.

Kartu KPI menampilkan nominal dan jumlah invoice di belakangnya.
Grafik batang membandingkan nilai lunas vs belum dibayar per bulan.
Donut chart memecah draft, unpaid, paid, dan overdue.
Tabel Recent Invoices di bawah untuk lompat cepat ke invoice terakhir.

Angka di dashboard dihitung dari status invoice, bukan dari input manual. Menandai invoice lunas langsung menggeser semua angka.

Dashboard desktop: KPI, grafik pendapatan, dan distribusi status.

Daftar Invoice

/invoices

Semua invoice dalam satu tabel: nomor, client, tanggal terbit, jatuh tempo, status, dan total. Ada pencarian, filter status, filter client, dan rentang tanggal.

Cari berdasarkan nomor invoice atau nama client.
Filter status: draft, unpaid, paid, cancelled — overdue ditandai otomatis dari tanggal.
Aksi per baris: lihat, edit, duplikat, unduh PDF/JPEG, bagikan link publik.
Nomor invoice mengikuti format INV-{YYYY}-{SEQ} dan berurutan otomatis.

Daftar invoice Invoisan di layar desktop

Daftar invoice dengan filter status, client, dan rentang tanggal.

Membuat Invoice

/invoices/create

Form dua kolom: data invoice di kiri, preview dokumen di kanan. Semua perubahan langsung terlihat di preview sebelum disimpan.

Pilih client dari master data, atau isi manual untuk klien sekali pakai.
Tambah item dari daftar produk, atur qty, harga, dan diskon per item.
Diskon global dan PPN dihitung otomatis saat mengetik.
Simpan sebagai draft dulu, lalu ubah status jadi unpaid saat siap dikirim.

Tombol duplikat di daftar invoice menyalin seluruh item dan client, jadi invoice bulanan cukup dibuat sekali.

Buat invoice: data di kiri, live preview dokumen di kanan.

Client & Produk

/clients • /products

Dua master data yang mempercepat pembuatan invoice: client (nama, perusahaan, alamat, email, telepon, NPWP) dan produk/jasa (nama, harga, deskripsi).

Sekali simpan, client dan produk bisa dipakai di semua invoice berikutnya.
Data client otomatis mengisi blok "Ditagihkan kepada" saat membuat invoice.
Produk menyimpan harga default supaya tidak salah ketik nominal.

Master client: alamat, email, telepon, dan NPWP tersimpan rapi.

Template & Branding

/templates

Tiga template bawaan (Clean, Classic, Modern). Warna primer, font, logo, NPWP, dan catatan footer bisa diubah tanpa menyentuh kode.

Ubah warna primer dan font, preview langsung ikut berubah.
Tampilkan atau sembunyikan logo perusahaan dan NPWP.
Tulis catatan footer untuk instruksi pembayaran atau syarat.
Jadikan satu template sebagai default untuk invoice baru.

Warna primer template tidak harus sama dengan warna aplikasi. Invoice bisa tetap memakai warna brand kamu sendiri.

Halaman template Invoisan dengan live preview

Template: warna, font, logo, dan NPWP dengan preview real-time.

Kirim Invoice

/invoices/{id}

Satu invoice bisa sampai ke klien lewat tiga jalur: link publik, pesan WhatsApp, atau email dengan lampiran PDF. Plus ekspor PDF/JPEG dan cetak kalau klien minta file.

Kirim lewat email — PDF invoice otomatis terlampir, klien tinggal buka.
Kirim lewat WhatsApp dengan pesan siap kirim berisi nomor invoice, nominal, dan link publik.
Bagikan link publik (token acak) supaya klien bisa membuka invoice tanpa akun.
Ekspor PDF/JPEG atau cetak langsung dari halaman detail invoice.
Status berubah jadi paid saat kamu tandai lunas, dan dashboard ikut ter-update.

Link publik bisa direset kapan saja lewat tombol regenerate token kalau link lama sudah tersebar.

Link publik: client membuka invoice tanpa login, lengkap dengan tombol unduh.

User & Role

/users

Dua role: admin (semua menu) dan staff (dashboard, invoice, client, produk). Cocok untuk tim kecil yang perlu input invoice tapi tidak boleh mengubah template atau setting.

Tambah user baru dari menu Users, tentukan role-nya.
Staff tidak melihat menu Templates, Users, dan Settings.
Setiap invoice mencatat siapa pembuatnya.

Tampilan mobile: menu yang sama, disusun ulang untuk layar kecil.

PWA di HP

Add to Home Screen

Invoisan adalah PWA: bisa dipasang di home screen Android/iOS dan punya halaman offline sederhana. Cocok untuk membuat invoice terakhir dari HP.

Buka aplikasi di browser HP, pilih Add to Home Screen.
Ikon, splash, dan status bar mengikuti manifest aplikasi.
Kalau koneksi putus, halaman offline muncul alih-alih error browser.

invoisan — dashboard

Dashboard Invoisan yang dipasang di home screen HP

Data yang sama, layout menyesuaikan layar: desktop dan HP.

Bantuan

Kalau ada yang tidak jalan

Masalah yang paling sering muncul saat pemasangan, beserta jalan keluarnya.

Folder vendor/ belum terisi. Di Docker, bind mount menutupi vendor/ yang sudah di-build ke dalam image — pastikan volume anonim /var/www/html/vendor masih ada di compose.yaml.

Di hosting tanpa Docker, jalankan composer install --no-dev dari root aplikasi (butuh Composer dan akses SSH/Terminal).

Perbaikan cepat

composer install --no-dev --optimize-autoloader
# atau, untuk Docker:
docker compose --env-file .env.compose up -d --build

Cek tiga nilai di .env: hostname, nama database, dan user. Di dalam Docker hostname-nya db (nama service), bukan localhost.

Kalau password di .env.compose diubah setelah volume MySQL dibuat, user lama tidak ikut berubah. Paling aman samakan password sejak awal, atau reset volume database kalau datanya masih kosong.

Cek koneksi dari container

docker compose --env-file .env.compose exec db \
  mysql -uinvoisan_user -p invoisan -e "select 1;"

app.baseURL harus sama persis dengan URL yang dibuka di browser, termasuk skema (http/https) dan diakhiri garis miring.

Kalau aplikasi di belakang reverse proxy HTTPS, set app.forceGlobalSecureRequests = true supaya asset dimuat lewat https.

Pastikan nginx/Apache meneruskan semua path ke public/index.php (rewrite), bukan hanya root. Konfigurasi contoh ada di docker/nginx/default.conf.

Token hanya dibuat untuk invoice yang sudah disimpan. Kalau baru membuat draft, buka detail invoice lalu tekan Share untuk membuat link.

Taruh folder inti (app/, vendor/, writable/, .env) di luar public_html, lalu salin semua isi public/ ke public_html. Sisanya cuma satu baris require di index.php.

public_html/index.php

require FCPATH . '../app/Config/Paths.php';
// ubah menjadi (sesuaikan nama folder inti):
require FCPATH . '../invoisan/app/Config/Paths.php';

Ekspor membutuhkan ekstensi gd dan intl. Di cPanel aktifkan lewat Select PHP Version → Extensions. Di Docker keduanya sudah terpasang di image.

Kalau hasil PDF terpotong, periksa catatan footer template — teks yang terlalu panjang menambah tinggi dokumen.

Cek ekstensi

php -m | grep -E "gd|intl|mbstring|mysqli"

Folder writable/ harus bisa ditulis user web server. Set 775 untuk folder dan 664 untuk file, lalu pastikan owner-nya sesuai (www-data di Debian/Ubuntu, apache di CentOS).

Upload dibatasi 2 MB oleh aplikasi; kalau hosting membatasi lebih kecil, naikkan upload_max_filesize dan post_max_size di php.ini.

Perbaikan permission

chown -R www-data:www-data writable
chmod -R 775 writable

AdminSeeder sengaja berhenti kalau tabel users sudah berisi data. Kalau kamu perlu membuat ulang, kosongkan tabel users dulu (hati-hati: invoice yang dibuat user tersebut ikut kehilangan relasi).

ADMIN_PASSWORD minimal 8 karakter. Seeder juga menolak email yang formatnya tidak valid.

Selesai, saatnya menagih

Kalau ada langkah yang kurang jelas atau lingkungan server-mu berbeda dari yang dijelaskan di sini, tanyakan langsung lewat WhatsApp. Sebutkan cara pemasangan yang kamu pakai supaya jawabannya cepat.

Lihat paket harga Pertanyaan umum Kembali ke beranda