Skip to content

Installation

Jump to bottom
Luc Garrabos edited this page May 6, 2026 · 1 revision

Installation

Get BookStorage running locally for development or deploy it on a Linux server for production use.

Table of contents

Prerequisites

Requirement Notes
Go 1.22+ Download Go
GCC Required for CGO (SQLite compilation)

Development setup

git clone https://github.com/LGARRABOS/BookStorage.git
cd BookStorage
go run ./cmd/bookstorage

The server starts on http://127.0.0.1:5000 by default.

Alternative run commands:

make run          # via Makefile
bsctl run         # via bsctl CLI

Optionally copy the environment template for local configuration:

cp .env.example .env

Defaults work for local development. See Configuration for all available settings.

Production installation (Linux)

Automatic installation

git clone https://github.com/LGARRABOS/BookStorage.git
cd BookStorage
sudo ./deploy/install.sh

The installer sets up:

  • Compiled application binary
  • bsctl CLI for service management (installed to /usr/local/bin)
  • systemd service (bookstorage.service) with EnvironmentFile=-/opt/bookstorage/.env
  • Firewall configuration
  • Bash completion for bsctl (when /etc/bash_completion.d/ exists)

Start the service

bsctl start

Prometheus (optional)

To install Prometheus alongside BookStorage:

INSTALL_WITH_PROMETHEUS=1 sudo -E ./deploy/install.sh

This installs the distribution prometheus package (or falls back to the official tarball), generates a BOOKSTORAGE_METRICS_TOKEN if missing, and enables the bookstorage-prometheus systemd unit (Prometheus UI on http://127.0.0.1:9091).

After installation:

sudo systemctl restart bookstorage
sudo systemctl status bookstorage-prometheus

See Configuration for metrics and Prometheus configuration details.

Scheduled backups (optional)

INSTALL_WITH_BACKUP_TIMER=1 sudo -E ./deploy/install.sh

This enables bookstorage-backup.timer for daily SQLite snapshots. See CI / CD for bsctl backup details.

Using a GitHub Actions artifact

As an alternative to cloning the repository, you can use the pre-built binary from GitHub Actions:

  1. Go to Actions > Deploy workflow and trigger a manual run
  2. Download the bookstorage-linux-amd64.tar.gz artifact
  3. Extract and copy the files:
tar xzf bookstorage-linux-amd64.tar.gz
sudo cp bookstorage /usr/local/bin/
sudo cp bsctl /usr/local/bin/
sudo cp bookstorage.service /etc/systemd/system/
  1. Use bsctl install and bsctl start as usual

Update recommendations

  • Prefer the latest major release (vX.0.0) for maximum stability in production.
  • Non-major releases (vX.Y.Z with Y > 0 or Z > 0) may ship with regressions that can break some features.
  • Before updating, back up at least database.db and the static/images / static/avatars folders, then smoke-test the app after restart.
  • Use bsctl update for managed updates — see CI / CD for the full command reference.

Configuration — Next: configure environment variables and site settings.

BookStorage Wiki

Clone this wiki locally