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 dengan MySQL/MariaDB atau SQLite. Ada tiga cara pasang: shared hosting (paling gampang), VPS dengan Docker (paling rapi), atau VPS native (tanpa Docker). Cara pasang dan pilihan database berdiri sendiri, database dipilih saat installer /setup berjalan.

PHP 8.2+intl, mbstring, gd, mysqli; sqlite3 kalau pakai SQLite

MySQL/MariaDB atau SQLitepilih salah satu saat /setup

writable/ bisa ditulisinstaller, session, cache, log, upload logo

Instalasi lewat browser. Tidak perlu menyunting .env atau menjalankan seeder manual. Buka /setup, isi nama aplikasi dan akun administrator, pilih MySQL/MariaDB atau SQLite, lalu pilih mulai kosong atau isi data contoh. Installer menulis .env, menjalankan migrasi, dan mengunci dirinya sendiri setelah selesai.

Shared HostingPaling gampang

Cocok kalau sudah punya paket hosting PHP. Tanpa SSH dan tanpa baris perintah: semuanya dari File Manager dan browser.

VPS + DockerPaling rapi

Satu perintah menyalakan aplikasi di VPS yang sudah punya Docker, tanpa perlu memasang PHP dan web server manual.

VPS NativeTanpa Docker

Kalau VPS sudah menjalankan Nginx dan PHP-FPM untuk situs lain, mode ini tidak menambah container. Instalasi tetap lewat /setup seperti cara lain.

Shared Hosting / cPanel

Cocok kalau sudah punya paket hosting PHP. Tanpa SSH dan tanpa baris perintah: semuanya dari File Manager dan browser.

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/     ← installer, session, cache, log
└── .env          ← dibuat installer saat setup

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

Siapkan database (opsional)

Kalau mau MySQL atau MariaDB: di cPanel → MySQL Databases, buat database dan user khusus, lalu beri akses penuh. Tidak perlu membuka phpMyAdmin; installer yang membuat skema lewat migrasi.

Kalau memilih SQLite, lewati langkah ini. Cukup pastikan folder writable/database bisa ditulis PHP.

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

Buka /setup

Pastikan folder writable/ bisa ditulis, lalu buka https://domainmu.id/setup dan isi formulirnya. Rincian tiap isian ada di bagian Setup awal.

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

Kalau butuh otomasi tanpa browser, salin .env.example menjadi .env, jalankan php spark migrate, lalu AdminSeeder dari Terminal cPanel.

VPS dengan Docker Compose

Satu perintah menyalakan aplikasi di VPS yang sudah punya Docker, tanpa perlu memasang PHP dan web server manual.

Salin template environment

Template sudah disiapkan di repo: .env.compose.example. Salin dulu, tidak perlu menulis file dari nol.

Terminal

cp .env.compose.example .env.compose

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

Ganti nilai di .env.compose

Buka .env.compose dengan nano atau editor favorit, lalu ganti empat baris ini. Sisanya (DB_NAME, DB_USER, DB_PORT, TZ) biarkan default.

.env.compose

# port web, bebas selama belum dipakai proses lain
APP_PORT=8080

# alamat aplikasi, harus diakhiri garis miring
APP_BASEURL=http://localhost:8080/

# wajib diganti sebelum dipakai produksi
DB_PASSWORD=ganti-password-kuat
DB_ROOT_PASSWORD=ganti-password-root-kuat

Kredensial database hanya dipakai kalau memilih MySQL/MariaDB; untuk SQLite isian ini diabaikan installer. Port database sengaja di-bind ke 127.0.0.1 (default 3307), jadi tidak bisa diakses dari luar server.

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. Tunggu sampai ps menampilkan status Up.

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. docker-compose.yml sudah menyiasatinya dengan volume anonim /var/www/html/vendor. Jangan dihapus, kalau tidak semua request jadi 500.

Buka /setup

Buka http://IP-server:8080/setup (atau domain yang diarahkan ke VPS), isi nama aplikasi dan akun administrator, lalu pilih database: MySQL/MariaDB (host db, port 3306, kredensial sama dengan .env.compose) atau SQLite (file di writable/database).

Data contoh berisi 4 client, 5 produk, dan 4 invoice dengan status berbeda. Jangan dipakai untuk data produksi.

VPS Tanpa Docker (Native)

Kalau VPS sudah menjalankan Nginx dan PHP-FPM untuk situs lain, mode ini tidak menambah container. Instalasi tetap lewat /setup seperti cara lain.

Pasang PHP, Nginx, dan database

Minimal PHP 8.2 dengan ekstensi intl, mbstring, dan gd. Contoh perintah untuk Debian/Ubuntu:

Paket Debian / Ubuntu

sudo apt update
sudo apt install nginx php8.2-fpm php8.2-intl \
  php8.2-mbstring php8.2-gd php8.2-mysql mariadb-server

Versi paket bisa berbeda tergantung distro. Yang penting PHP 8.2 atau lebih baru. Mau SQLite? Pasang juga php8.2-sqlite3 dan lewati MariaDB.

Arahkan document root ke public/

Ini langkah keamanan paling penting di mode native: web server hanya boleh menyentuh folder public/. Semua permintaan diarahkan ke index.php di dalamnya.

/etc/nginx/sites-available/invoisan

server {
    listen 80;
    server_name invoice.domainmu.com;
    root /var/www/invoisan/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?/$request_uri;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* { deny all; }
}

Aktifkan dengan symlink ke sites-enabled, lalu jalankan nginx -t dan systemctl reload nginx.

Atur izin tulis & buka /setup

Web server perlu bisa menulis di writable/ dan membuat .env. Kalau folder vendor/ belum ada (clone dari repo), jalankan composer install --no-dev lebih dulu.

Izin folder

sudo chown -R www-data:www-data /var/www/invoisan
sudo chmod -R 775 /var/www/invoisan/writable

Buka https://domainmu.com/setup. Formnya sama seperti cara lain, dan rincian isiannya ada di bagian Setup awal.

Setup awal lewat /setup

Installer satu halaman: identitas aplikasi, akun administrator, pilihan database, lalu data awal. Tidak ada file yang perlu diedit manual.

Buka /setup

Buka alamat aplikasi diikuti /setup. Selama aplikasi belum terpasang, halaman ini yang tampil pertama. Setelah instalasi selesai, installer mengunci dirinya sendiri.

Alamat installer

https://domainanda.com/setup

Mau memasang ulang? Hapus writable/installed.lock, kosongkan database, lalu buka /setup lagi.

Isi identitas dan akun administrator

Nama aplikasi (2–60 karakter) dipakai di judul halaman dan dokumen. Akun administrator butuh nama, email valid, dan password minimal 8 karakter. Akun inilah yang dipakai untuk login pertama.

Pilih database

Pilih MySQL/MariaDB lalu isi host, port, nama database, user, dan password. Host db kalau aplikasi jalan di Docker, localhost kalau manual. Atau pilih SQLite: installer memakai file di writable/database dan membuat foldernya kalau belum ada.

Database MySQL/MariaDB harus kosong. Installer menolak database yang sudah berisi akun pengguna.

Pilih data awal, lalu install

Mulai kosong untuk data produksi, atau isi data contoh (4 client, 5 produk, 4 invoice) buat mencoba fitur. Klik Install: installer menulis .env, menjalankan migrasi, membuat akun admin, dan mengarahkan ke halaman login.

Setelah selesai, /setup terkunci. Langkah berikutnya ada di bagian Login pertama.

Pilihan database

MySQL/MariaDB atau SQLite, semuanya disiapkan installer. Cara pasang tidak menentukan pilihan ini: Docker maupun manual bisa memakai salah satunya.

MySQL / MariaDB

Paling umum di VPS dan paket hosting. MySQL 8 atau MariaDB 10.6+, driver dan perilakunya sama.

Butuh server database terpisah
Aman untuk banyak pengguna

SQLite

Satu file di writable/database, tanpa server database. Cocok untuk tim kecil.

Backup cukup salin file .db
Cocok untuk satu server kecil

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 buat di installer. 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

Kalau instalasi sudah selesai, /setup memang dikunci lewat writable/installed.lock. Hapus lock itu hanya kalau database masih kosong dan kamu benar-benar ingin mengulang instalasi.

Kalau aplikasi lama malah diarahkan ke /setup, pastikan folder writable/ bisa ditulis. Aplikasi membuat lock otomatis begitu mendeteksi tabel users sudah berisi akun.

Installer menolak database yang sudah punya akun. Pakai database kosong atau kosongkan data lama dulu.

Perbaikan permission

chown -R www-data:www-data writable
chmod -R ug+rwX writable

Wizard /setup adalah jalur utama. Kalau butuh otomasi, salin .env.example menjadi .env, jalankan migrasi, lalu AdminSeeder dari root aplikasi.

AdminSeeder berhenti kalau tabel users sudah berisi data. ADMIN_PASSWORD minimal 8 karakter dan email harus valid.

Terminal

cp .env.example .env
php spark migrate
ADMIN_NAME="Nama Kamu" [email protected] ADMIN_PASSWORD='password-kuat' php spark db:seed AdminSeeder

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