Installation

Docker Compose

The easiest way to get started is using Docker Compose. This method requires minimal setup and handles all dependencies automatically.

Prerequisites:

• Docker and Docker Compose installed on your system

Installation steps:

1. Create a new directory for your Zen installation:

$ mkdir zen && cd zen

2. Create a docker-compose.yml file:

services:
  zen:
    image: ghcr.io/sheshbabu/zen/zen:latest
    container_name: zen
    network_mode: 'bridge'
    ports:
      - 8080:8080
    volumes:
      - /path/to/data:/data
      - /path/to/images:/images
    restart: 'unless-stopped'

3. Start the application:

docker-compose up -d

4. Access Zen in your browser at http://localhost:8080

Note: Your notes and images will be stored in the ./data and ./images directories respectively, ensuring your data persists between container restarts.

Build from Scratch

For developers who want more control or need to modify the source code, you can build Zen from the source repository.

Prerequisites:

• Go 1.23 or later
• Git
• esbuild

Build steps:

1. Clone the repository:

$ git clone https://github.com/sheshbabu/zen.git
$ cd zen

2. Build the application:

make build

3. Run the application:

./zen

4. Access Zen in your browser at http://localhost:8080

Keyboard Shortcuts

Shortcuts use Ctrl on Windows/Linux and Cmd on macOS.

Global Shortcuts

These shortcuts work from anywhere in the application:

• Ctrl/Cmd + N - Create a new note
• Ctrl/Cmd + K - Open search
• Escape - Close modals and dialogs

Editor Shortcuts

These shortcuts work when editing notes:

• Ctrl/Cmd + Enter - Save note (or start editing when viewing)
• Ctrl/Cmd + B - Bold selected text
• Ctrl/Cmd + Shift + H - Highlight selected text
• Tab - Insert indentation (2 spaces)
• Escape - Close floating editor

Navigation Shortcuts

These shortcuts help you navigate through search results and suggestions:

• Arrow Up/Down - Navigate through search results
• Enter - Select highlighted search result or tag suggestion
• Escape - Close search or tag suggestions
• Backspace - Close tag suggestions when input is empty

Image Gallery Shortcuts

These shortcuts work when viewing images in the lightbox:

• Escape - Close the image lightbox
• Arrow Left - Navigate to previous image
• Arrow Right - Navigate to next image

Tip: Most shortcuts work contextually, they only activate when you're in the relevant part of the interface.

Backup

PowerShell

To back up your notes, you can use the following PowerShell script. This script creates a timestamped backup of your SQLite database and verifies its integrity.

$sourceDbPath  = "C:\path\to\data\zen.db"
$timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
$backupDbPath = "C:\path\to\backup\zen_backup_$timestamp.db"

Write-Host "Backing up Zen..."

sqlite3 $sourceDbPath ".backup '$backupDbPath'"

Write-Host "`n--- Checking integrity of the backup database ---"
$integrityResult = sqlite3 $backupDbPath "PRAGMA integrity_check;"
$integrityResult = $integrityResult.Trim()

if ($integrityResult -eq "ok") {
    Write-Host "Backup successful and verified: $backupDbPath"
    Write-Host "`n--- Checking for notes in the backup database ---"
    $notesCheckOutput = sqlite3 $backupDbPath "SELECT COUNT(*) FROM notes;"
    $notesCheckOutput = $notesCheckOutput.Trim()

    if ($notesCheckOutput -match "^\d+$") {
        $notesCount = [int]$notesCheckOutput
        if ($notesCount -gt 0) {
            Write-Host "Notes table found with $notesCount rows."
        } else {
            Write-Host "Notes table exists but is empty (0 rows)."
        }
    } elseif ($notesCheckOutput -like "Error: no such table:*") {
        Write-Host "Notes table not found in the backup database."
    } else {
        Write-Host "Could not determine notes table status. SQLite output: '$notesCheckOutput'"
    }

} else {
    Write-Host "Backup verification failed for: $backupDbPath"
    Write-Host "Integrity check result: '$integrityResult'"
}

# Restart so the WAL file is created again
Write-Host "`nRestarting Zen..."
docker compose restart