2. Getting Started

This section walks you through every step — from downloading and installing NkapBooks to completing the initial setup and onboarding checklist so your books are ready for real transactions.

2.1 Installation

System Requirements

Windows

NkapBooks is distributed as an .exe installer (NSIS) and an .msi package for enterprise deployments.

Standard Installation (Recommended):

1. Download the latest .exe installer from the releases page.
2. Double-click the downloaded file to launch the installer.
3. If Windows Defender SmartScreen appears, click "More info" → "Run anyway". This happens because the app is not yet code-signed with an EV certificate.
4. Follow the installation wizard — choose the install directory and click Install.
5. Launch NkapBooks from the Start Menu or the Desktop shortcut.

Silent MSI Installation (Enterprise):

For automated or group-policy deployments, use the MSI package:

msiexec /i NkapBooks-x.x.x.msi /qn

Add /l*v install.log for verbose installation logging.

Portable Mode:

No portable build is officially distributed, but the installed application stores all user data separately from the program files (see Data Location below), making it safe to install over previous versions.

macOS

NkapBooks is distributed as a .dmg disk image.

1. Download the appropriate .dmg file from the releases page:
   • Universal — works on both Intel and Apple Silicon Macs.
   • Apple Silicon — optimized for M1/M2/M3/M4 processors.
   • Intel — for older Intel-based Macs.
2. Double-click the .dmg to mount it.
3. Drag NkapBooks into your Applications folder.
4. Open NkapBooks from Applications or Launchpad.
5. If macOS warns about an unidentified developer:
   • Go to System Settings → Privacy & Security.
   • Click "Open Anyway" next to the NkapBooks message.
   • Alternatively, run in Terminal: xattr -cr /Applications/NkapBooks.app

Homebrew (alternative):

brew install --cask nkapbooks

Update with: brew upgrade --cask nkapbooks

Minimum macOS version: 10.13 (High Sierra) — as configured in the Tauri build, though macOS 11+ is recommended.

Linux

NkapBooks is available in multiple package formats:

AppImage (Universal — works on most distributions):

# Download
wget https://nkapbooks.ddns.net/downloads/NkapBooks-x.x.x.AppImage

# Make executable
chmod +x NkapBooks-x.x.x.AppImage

# Run
./NkapBooks-x.x.x.AppImage

Tip: Use AppImageLauncher to integrate AppImages into your desktop environment. If the AppImage won't run, ensure FUSE is installed: sudo apt install fuse libfuse2 (Debian/Ubuntu) or sudo dnf install fuse (Fedora).

Debian / Ubuntu (.deb):

sudo apt install ./nkapbooks_x.x.x_amd64.deb

Or via dpkg: sudo dpkg -i nkapbooks_x.x.x_amd64.deb && sudo apt-get install -f

Fedora / RHEL (.rpm):

sudo dnf install ./nkapbooks-x.x.x.x86_64.rpm

Flatpak (Flathub):

flatpak install flathub io.gitss.nkapbooks
flatpak run io.gitss.nkapbooks

Data Location

NkapBooks stores user data (SQLite database files, configuration, backups) separately from the application itself:

Important: Uninstalling NkapBooks does not delete your data. To completely remove all data, manually delete the data directory after uninstalling.

Verifying Your Download

Compare the SHA-256 checksum of your download with the value published on the releases page:

• Windows (PowerShell): Get-FileHash NkapBooks-x.x.x-setup.exe -Algorithm SHA256
• macOS / Linux: sha256sum NkapBooks-x.x.x.AppImage

Auto-Updates

NkapBooks includes a built-in auto-update mechanism powered by the Tauri Updater plugin:

1. On launch, the app checks the update endpoint for a newer version.
2. If an update is available, a progress overlay appears in the bottom-right corner showing download progress (downloaded bytes, total size, percentage) and stage indicators (Checking → Downloading → Installing → Ready to restart).
3. Once downloaded, you can click "Restart Now" to apply the update, or "Later" to dismiss and apply it on next launch.

Updates are verified using Ed25519 public key signatures to ensure authenticity.

Uninstalling

• Windows: Settings → Apps → Apps & features → find NkapBooks → Uninstall.
• macOS: Drag NkapBooks from Applications to the Trash.
• Linux (deb): sudo apt remove nkapbooks | (rpm): sudo dnf remove nkapbooks | (Flatpak): flatpak uninstall io.gitss.nkapbooks

2.2 Database Selector

On first launch — or whenever no previous database is remembered — NkapBooks displays the Database Selector screen. This is the entry point for creating or opening a company.

Welcome Screen Layout

The Database Selector is divided into two tabs:

SQLite (Local) Tab

This is the default tab. It presents three options:

A Demo Company option is available (with a pink beaker icon) to create a pre-populated sample database with fictitious data — useful for exploring NkapBooks before entering real business data. The demo is created by running the full Setup Wizard with pre-defined values and then generating sample transactions.

PostgreSQL (Server) Tab

For multi-user or networked environments, this tab provides a PostgreSQL connection form:

Actions:

• Test Connection — Validates the connection parameters without making any changes. Shows a green "Connection successful!" or red "Connection failed" status indicator.
• Create Database — Creates a new PostgreSQL database with the specified name and opens the Setup Wizard.
• Connect — Connects to an existing PostgreSQL database that was previously set up.

Header Controls

The Database Selector header includes:

• Language Selector — A dropdown to change the application language before opening any database.
• Dark Mode Toggle — A sun/moon icon button to switch between light and dark themes.

How the Database Selector Works

1. When NkapBooks launches, it checks lastDatabaseType and lastSelectedFilePath (or lastPostgresConfig) from the local configuration store.
2. If a previous database path or PostgreSQL config is found, NkapBooks attempts to reconnect automatically.
3. If reconnection fails (e.g., file deleted, server unreachable), or if no previous database exists, the Database Selector is shown.
4. After selecting or creating a database, the application proceeds to either the Setup Wizard (for new databases) or the Login / Desk screen (for existing databases).

2.3 Setup Wizard

When you create a new company (either SQLite or PostgreSQL), the Setup Wizard guides you through the initial configuration. The wizard is a single-page form with multiple sections.

Setup Wizard Fields

The wizard collects the following information, organized into sections:

Default Section

Identity Section

Locale Section

Accounting Section

Header Controls

The Setup Wizard header includes:

• Language Selector — Change the interface language during setup.
• Dark Mode Toggle — Switch between light and dark themes during setup.

Buttons

• Cancel — Aborts the setup and returns to the Database Selector.
• Fill — (Development mode only) Auto-fills the form with sample data for testing.
• Submit — Validates that all required fields are filled, then begins the setup process.

Setup Progress Overlay

After clicking Submit, a progress overlay appears in the bottom-right corner showing the setup process in real-time. The setup progresses through 7 stages:

What Gets Created During Setup

Here is a comprehensive list of everything the Setup Wizard creates:

1. Database schema — All tables for every document type (accounts, invoices, payments, items, parties, journal entries, inventory, POS, users, roles, etc.).
2. System Settings — Date format, locale, currency, display precision, country code, dark mode preference, session timeout, authentication settings.
3. Accounting Settings — Company name, email, country, fiscal year start/end, bank name, feature flags (all disabled by default).
4. Print Settings — Company name, default color (#112B42 "Black"), default font (Arial), display options (logo, amount in words, time).
5. Currency record — Full currency configuration based on country.
6. Chart of Accounts — Complete account tree based on the selected template.
7. Bank Account — A non-group account under the appropriate parent bank account group.
8. Discount Account — For SYSCOHADA countries, a specific discount account is created under the appropriate income account.
9. Regional records — Country-specific tax templates and settings.
10. Default entries — Units of measure, item groups, and other seed data.
11. Number Series — Auto-incrementing number series for all document types (Sales Invoice, Purchase Invoice, Payment, Journal Entry, Sales Quote, Stock Movement, Shipment, Purchase Receipt, etc.).
12. Inventory Settings — Default stock account, stock received but not billed account, cost of goods sold account, stock adjustment account, and default location (warehouse).
13. Print Templates — Default print templates for all printable document types.
14. Payment & POS Defaults — Default payment account and default POS location.
15. Admin User — User record with Administrator and System Manager roles.
16. GetStarted record — Onboarding checklist state (all items unchecked).

2.4 Login Screen

After the Setup Wizard completes (or when opening an existing database with authentication enabled), the Login screen is displayed.

Login Form Fields

Actions

• Sign In — Authenticates the user against the database. On success, proceeds to the Desk.
• Skip — (Only shown when SystemSettings.allowSkipAuth is enabled) Bypasses authentication. Not recommended for multi-user environments.
• Forgot password? — (Only shown when SystemSettings.allowPasswordReset is enabled) Opens a modal to request password reset instructions via email.

Authentication Behavior

• Authentication is controlled by the SystemSettings.requireAuth setting (default: true).
• When requireAuth is false, the Login screen is skipped entirely and the user goes directly to the Desk.
• After successful login, session monitoring begins. The session timeout is configurable via SystemSettings.sessionTimeout (default: 60 minutes, range: 5–1440 minutes).
• When the session is about to expire, a Session Timeout Warning overlay appears giving the user a chance to extend the session.
• When the session expires, a Session Lock screen requires re-authentication.

Header Controls

Like other pre-desk screens, the Login page includes:

• Language Selector — Switch the interface language.
• Dark Mode Toggle — Switch between light and dark themes.

Keyboard Shortcuts

• Ctrl+Alt+Shift+D — Switch to a different database file (available on the Login screen).

2.5 Get Started Checklist

After setup is complete and you've logged in, the Get Started page provides a guided onboarding flow to help you configure the most important aspects of your business before creating your first transactions. This page is accessible from the sidebar under "Get Started" and is hidden automatically once all tasks are completed.

How It Works

• Each task is displayed as a card with an icon, title, description, and action buttons.
• Hover over a card to reveal the "Set Up" and/or "Documentation" buttons.
• When a task is completed, the card shows a green checkmark icon.
• NkapBooks automatically detects completed tasks on page load (e.g., if you've already created a customer, the "Add Customers" card is auto-checked).
• Once all tasks are marked as complete, the onboardingComplete flag is set, SystemSettings.hideGetStarted is enabled, and the "Get Started" item is hidden from the sidebar.

Organisation Section

What You Configure in General (Accounting Settings)

What You Configure in Print (Print Settings)

What You Configure in System (System Settings)

Accounts Section

Sales Section

Auto-Detection

NkapBooks automatically checks whether these tasks have been completed:

• Sales Items: Counts Item records where for = 'Sales'.
• Customers: Counts Party records where role = 'Customer'.
• Sales Invoice: Counts SalesInvoice records.

If any count is greater than 0, the corresponding task is automatically marked as complete.

Purchases Section

Auto-Detection

• Purchase Items: Counts Item records where for = 'Purchases'.
• Suppliers: Counts Party records where role = 'Supplier'.
• Purchase Invoice: Counts SalesInvoice records (note: both sales and purchase invoice creation are tracked to indicate general invoice familiarity).

Onboarding Completion

The onboarding is considered complete when every tracked field in the GetStarted schema is set to true. The tracked fields are:

Once all 12 fields are checked:

1. The onboardingComplete field is set to true.
2. SystemSettings.hideGetStarted is set to true.
3. The "Get Started" sidebar item disappears.
4. The user is automatically redirected to the Dashboard on next navigation.

Note: You can always re-access the setup screens from the Setup → Settings sidebar item, even after the onboarding is complete.

2.6 Keyboard Shortcuts Reference

NkapBooks provides comprehensive keyboard shortcuts for efficient navigation. Here is the complete reference:

Global Shortcuts

Entry (Form) Shortcuts

List View Shortcuts

Quick Search Shortcuts

Template Builder Shortcuts

Point of Sale (POS) Shortcuts

Special Shortcuts

Tip: Access the complete shortcuts reference at any time by clicking "Shortcuts" in the sidebar footer or pressing the keyboard shortcut icon.

2.7 Quick Start Summary

Here's the fastest path from installation to your first invoice:

1. Download & Install NkapBooks for your platform.
2. Launch the application → the Database Selector appears.
3. Click "New Company" → the Setup Wizard opens.
4. Fill in your Company Name, Full Name, Email, Username, Password, Country, Currency, Bank Name, Chart of Accounts, and Fiscal Year dates.
5. Click Submit → watch the 7-stage progress bar complete.
6. Log in with the credentials you just created (or skip if auth is disabled).
7. On the Get Started page:
   • Click General → review your company settings → close.
   • Click Add Sales Items → add at least one product or service.
   • Click Add Customers → add at least one customer.
   • Click Create Sales Invoice → create and submit your first invoice.
8. Explore the Dashboard to see your financial overview.
9. Continue with the remaining onboarding tasks at your own pace.

You're now up and running with NkapBooks!