Skip to content

setup.md

Latest commit

 

History

History
146 lines (110 loc) · 4.59 KB

setup.md

File metadata and controls

146 lines (110 loc) · 4.59 KB
Raw
title Setup
description Install docbank on Linux, macOS, or Windows and create the vault.

Setup

Install a release archive to start using Docbank without a build toolchain. Docbank is pre-1.0 and runs on Linux, macOS, and 64-bit Windows, on amd64 and arm64 processors.

Requirements

  • Linux, macOS, or 64-bit Windows on amd64 or arm64.

Installing a release archive needs no build toolchain. Building from source additionally requires:

  • Go 1.27 or newer with CGO enabled — the store uses mattn/go-sqlite3
  • A C compiler (Xcode command-line tools on macOS, gcc/clang on Linux, or a MinGW-compatible compiler on Windows)
  • Node.js 24 or newer and npm — source builds compile the embedded web application before the Go binary

Install a release

Published releases include Linux, macOS, and Windows archives for amd64 and arm64 with SHA-256 checksums. The shell and PowerShell installers select the native archive and verify it against SHA256SUMS before installing, failing rather than substituting an incompatible or unverified archive.

On Linux or macOS, the installer selects the native archive and installs docbank to ~/.local/bin by default:

curl -fsSL https://docbank.ai/install.sh | sh

Set DOCBANK_INSTALL_DIR to choose another destination. Set DOCBANK_VERSION=vX.Y.Z to install a specific release rather than the latest.

On Windows, run the PowerShell installer:

irm https://docbank.ai/install.ps1 | iex

It installs to %LOCALAPPDATA%\Programs\docbank\bin and adds that directory to the user PATH. DOCBANK_INSTALL_DIR and DOCBANK_VERSION provide the same overrides as on Unix; set DOCBANK_NO_MODIFY_PATH=1 to leave PATH unchanged.

The repository maintains both installers as scripts/install.sh and scripts/install.ps1; docbank.ai serves the same files. To fetch the shell installer directly from GitHub instead, run:

curl -fsSL https://raw.githubusercontent.com/kenn-io/docbank/main/scripts/install.sh | sh

Neither installer extracts or installs an archive unless SHA256SUMS is available, has exactly one matching entry, and the checksum matches. Each installer also rejects archives containing anything other than the expected top-level executable.

Manual installation

  1. Download your platform's archive and SHA256SUMS from GitHub Releases.
  2. Verify the archive against its entry in SHA256SUMS.
  3. Extract the archive.
  4. Place docbank on your PATH, for example in ~/.local/bin.

Release archives are named:

docbank_<version>_<goos>_<goarch>.tar.gz  # Linux and macOS
docbank_<version>_windows_<goarch>.zip    # Windows

Releases publish all six archives. An installer fails instead of substituting another platform. Never install an archive for a different OS or architecture.

Build and install from source

git clone https://github.com/kenn-io/docbank.git
cd docbank
make build      # builds ./docbank
make install    # installs to ~/.local/bin

On Windows, use a PowerShell prompt with Go and the C compiler available:

Push-Location frontend
npm ci
npm run build
Pop-Location
Get-ChildItem internal/web/dist -Force |
  Where-Object Name -ne '.keep' |
  Remove-Item -Recurse -Force
Copy-Item -Recurse -Force frontend/dist/* internal/web/dist/
go build -tags fts5 -o docbank.exe ./cmd/docbank
go test -tags fts5 ./...

The SQLite full-text index requires the fts5 build tag; the Makefile targets set it for you and build the frontend first. If you invoke go directly on Unix, prepare the embedded frontend and pass the tag yourself:

(cd frontend && npm ci && npm run build)
find internal/web/dist -mindepth 1 ! -name .keep -exec rm -rf {} +
cp -R frontend/dist/. internal/web/dist/
go build -tags fts5 ./cmd/docbank
go test -tags fts5 ./...

First run

There is no init step. The first command you run creates the vault layout under ~/.docbank/ (database, blob directory, lock file):

docbank add ~/Desktop/some-document.pdf
docbank ls /inbox

Set DOCBANK_HOME to keep the vault somewhere else — see Configuration.

Before importing irreplaceable material, choose a backup location and plan a restore test. Vault Lifecycle explains the operating routine, and Backup & Restore gives the commands.

Verifying the toolchain

make test    # full test suite
make lint    # golangci-lint

Both must pass cleanly on a supported platform. If go test fails with undefined: ...fts5... errors, the fts5 tag is missing.