Skip to content

Setup_en

sensboston edited this page Oct 25, 2026 · 4 revisions

TinyOPDS Installation and Setup

System Requirements

Minimum Requirements

  • For small libraries (up to 50,000 books):
    • Processor: ARM Cortex-A53 1 GHz or x86/x64 1 GHz
    • Memory: 1 GB RAM
    • Disk space: 100 MB + database size
    • OS: Windows 10 version 1903+, Windows 11, Windows 7 SP1/8/8.1 (requires .NET 4.8 installation), Linux, macOS 10.12+
    • .NET Framework: 4.8 (for Windows)
    • Works even on Raspberry Pi Zero 2 W

Recommended Requirements

  • For large libraries (500,000+ books):
    • Processor: multi-core 2+ GHz
    • Memory: minimum 4 GB RAM
    • Disk space: 500 MB + database size
    • SSD drive for fast scanning

Note: Database size is approximately 3-4 MB per 1000 books. For a library of 500,000 books, the database will take about 1.7 GB.

Platform Support

Platform GUI Version CLI Version Wine Support
Windows ✅ Full support ✅ Full support N/A
Linux ✅ Full support (via Mono) ✅ Full support ✅ Full support
macOS ❌ Not supported* ✅ Full support ✅ Full support
Docker (NAS) N/A ✅ Docker image, amd64 and arm64 (beta) N/A

NAS and Docker: see TinyOPDS in Docker (NAS).

macOS Note: The GUI version cannot run natively on macOS due to WinForms incompatibility with 64-bit Mono. Use either the CLI version or Wine for GUI functionality.

GUI Version Installation

Windows

  1. Download the latest version from GitHub Releases
  2. Extract the archive to any folder
  3. For Windows 7 SP1, 8, 8.1 - install .NET Framework 4.8 if not present
  4. Run TinyOPDS.exe

The program is completely portable and requires no installation. All settings are saved in the TinyOPDS.config file in the program folder.

Note: Windows 10 version 1903 and higher, as well as Windows 11, already include .NET Framework 4.8.

Linux

Installing Mono

Ubuntu/Debian:

sudo apt update
sudo apt install mono-complete

Fedora/CentOS/RHEL:

sudo dnf install mono-complete

Arch Linux:

sudo pacman -S mono

openSUSE:

sudo zypper install mono-complete

Running TinyOPDS

# Make the file executable
chmod +x TinyOPDS.exe

# Run via Mono
mono TinyOPDS.exe

macOS

Important: The GUI version does not work natively on macOS due to WinForms incompatibility with 64-bit Mono. You have three options:

  1. Use the CLI version (recommended)
  2. Use Wine to run the GUI version
  3. Configure settings on Windows/Linux and copy the config file

Option 1: CLI Version (Recommended)

Installing Dependencies:

# Install Homebrew if not present
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Mono
brew install mono

# IMPORTANT: Install fresh SQLite to avoid crashes
brew install sqlite

Running CLI Version:

# Navigate to program folder
cd /path/to/tinyopds

# Scan library
mono TinyOPDSCLI.exe scan

# Start server
mono TinyOPDSCLI.exe start

SQLite Note: macOS system SQLite has compatibility issues with Mono.Data.Sqlite. Installing SQLite via Homebrew resolves crashes during scanning.

Option 2: Wine (For GUI)

# Install Wine via Homebrew
brew install --cask wine-stable

# Run GUI version
wine TinyOPDS.exe

# Create an app shortcut (optional)
echo '#!/bin/bash
cd "$(dirname "$0")"
wine TinyOPDS.exe 2>/dev/null &' > TinyOPDS.app/Contents/MacOS/TinyOPDS
chmod +x TinyOPDS.app/Contents/MacOS/TinyOPDS

Running with Wine (Alternative Method)

Wine allows running the Windows version on Linux and macOS with full GUI functionality.

Installing Wine

Linux:

# Ubuntu/Debian
sudo apt install wine wine32

# Fedora
sudo dnf install wine

# Arch
sudo pacman -S wine

macOS:

brew install --cask wine-stable

Running TinyOPDS with Wine

# Basic run
wine TinyOPDS.exe

# Run without console output
wine TinyOPDS.exe 2>/dev/null

# Run in background
nohup wine TinyOPDS.exe > /dev/null 2>&1 &

Creating Desktop Shortcuts

Linux (.desktop file):

[Desktop Entry]
Name=TinyOPDS
Comment=OPDS Book Server
Exec=wine /path/to/TinyOPDS.exe
Icon=/path/to/icon.png
Terminal=false
Type=Application
Categories=Network;

macOS (Automator App):

  1. Open Automator
  2. Create new Application
  3. Add "Run Shell Script" action
  4. Enter: cd /path/to/tinyopds && wine TinyOPDS.exe 2>/dev/null
  5. Save as TinyOPDS.app

Installing Console Version as a Service

TinyOPDSCLI can be installed as a system service for automatic startup at system boot.

Important: Before installing the service, it's recommended to first configure all settings via the GUI version (TinyOPDS.exe), then use the ready TinyOPDS.config configuration file for the console version.

Windows

The console version uses SC.EXE to register a Windows service:

# Open command prompt as Administrator

# Install service
TinyOPDSCLI.exe install

# Start service
TinyOPDSCLI.exe start

# Stop service
TinyOPDSCLI.exe stop

# Uninstall service
TinyOPDSCLI.exe uninstall

Windows service features:

  • Installed with automatic startup (delayed-auto)
  • Runs under LocalSystem
  • Recovery policy configured (restart on failure)
  • Logs saved to TinyOPDS.log file in program folder

Linux

The installer automatically detects the init system (systemd or init.d):

# Root privileges required
sudo mono TinyOPDSCLI.exe install

# Service management
sudo mono TinyOPDSCLI.exe start
sudo mono TinyOPDSCLI.exe stop
sudo mono TinyOPDSCLI.exe uninstall

Systemd (modern distributions)

During installation, the file /etc/systemd/system/tinyopds.service is created:

[Unit]
Description=TinyOPDS OPDS Server
After=network.target

[Service]
Type=simple
User=tinyopds
Group=tinyopds
WorkingDirectory=/opt/tinyopds
Environment="TINYOPDS_SERVICE=1"
ExecStart=/usr/bin/mono /opt/tinyopds/TinyOPDSCLI.exe start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

File locations:

  • Data: /var/lib/tinyopds/
  • Logs: /var/log/tinyopds/
  • Configuration: in program folder

Init.d (older distributions)

Script /etc/init.d/tinyopds is created with standard init.d command support (the script itself supports status, but TinyOPDSCLI.exe doesn't have this command)

macOS

Uses launchd for service management:

# IMPORTANT: Install SQLite first
brew install sqlite

# Installation (requires sudo for system service)
sudo mono TinyOPDSCLI.exe install

# Or install for current user (without sudo)
mono TinyOPDSCLI.exe install

# Service management
mono TinyOPDSCLI.exe start
mono TinyOPDSCLI.exe stop
mono TinyOPDSCLI.exe uninstall

System Service (LaunchDaemon)

When installing with root privileges, /Library/LaunchDaemons/com.senssoft.tinyopds.plist is created:

  • Starts at system boot
  • Runs in background for all users
  • Logs: /usr/local/var/log/tinyopds/

User Service (LaunchAgent)

When installing without root, ~/Library/LaunchAgents/com.senssoft.tinyopds.plist is created:

  • Starts at user login
  • Runs only for current user
  • Logs: ~/Library/Logs/TinyOPDS/

macOS service features:

  • Automatic restart on failure
  • 5 second delay between restarts
  • Apple Silicon (M1/M2) and Intel support
  • Requires Homebrew SQLite for stability

Initial Setup

1. Library Setup

  1. Start TinyOPDS (GUI or CLI)
  2. For GUI: Go to "Scanner" tab
  3. Specify path to books folder
  4. Click "Start scanning" or use mono TinyOPDSCLI.exe scan

2. Server Setup

  1. For GUI: Go to "Server" tab
  2. If your computer has multiple network cards, select the appropriate network interface
  3. Set port (default 8080)
  4. Click "Start server" or use mono TinyOPDSCLI.exe start

Note: By default, the server listens on all network interfaces. Selecting a specific interface is only needed when multiple network cards are present.

3. Verify Operation

Open a browser and navigate to:

  • Local access: http://localhost:8080/
  • Network: http://[your-ip]:8080/
  • OPDS catalog: http://[your-ip]:8080/opds

Configuration Files

Recommendation: For the console version, first configure all settings via the GUI version, then copy the TinyOPDS.config file to the folder with TinyOPDSCLI.exe. If both executable files are in the same folder, they automatically use the shared configuration file.

Windows

  • Settings: TinyOPDS.config
  • Database: books.sqlite in program folder
  • Logs: TinyOPDS.log in program folder

Linux/macOS

  • Settings: TinyOPDS.config
  • Database: books.sqlite in program folder
  • Program logs: TinyOPDS.log in program folder
  • Service logs: /var/log/tinyopds/ (Linux) or ~/Library/Logs/TinyOPDS/ (macOS)

Updating

  1. Stop the service/program
  2. Save a copy of the books.sqlite database
  3. Replace program files with new version
  4. Start the program/service

The database is compatible between versions and requires no conversion.

Troubleshooting

macOS Native GUI Not Working

The GUI version cannot run natively on macOS due to Mono's WinForms implementation being incompatible with 64-bit mode. You will see this error:

WARNING: The Carbon driver has not been ported to 64bits, and very few parts of Windows.Forms will work properly, or at all

Solutions:

  1. Use the CLI version (fully functional)
  2. Run GUI version with Wine
  3. Configure on Windows/Linux and copy the config file

macOS SQLite Crashes

If you experience crashes during scanning on macOS, install Homebrew's SQLite:

brew install sqlite

This resolves compatibility issues between Mono.Data.Sqlite and macOS system SQLite.

Service Won't Start

Windows:

# Check service status
sc query TinyOPDS

# View logs in Event Viewer
eventvwr.msc

Linux:

# For systemd
sudo systemctl status tinyopds
sudo journalctl -u tinyopds -f

# For init.d
sudo service tinyopds status
tail -f /var/log/tinyopds/*.log

macOS:

# Check status
launchctl list | grep tinyopds

# View logs
tail -f ~/Library/Logs/TinyOPDS/*.log
# or for system service
tail -f /usr/local/var/log/tinyopds/*.log

Error "Port already in use"

Change the port in settings or find the process using the port:

# Linux/macOS
lsof -i :8080

# Windows
netstat -ano | findstr :8080

Slow Scanning

  • Use SSD for database
  • Perform initial scan on a powerful computer
  • Copy ready database to target device

Security

Access Restriction

  1. Use HTTP authorization ("Auth" tab)
  2. Configure firewall to restrict access by IP
  3. Use VPN for remote access

Backup

Regularly save copies of:

  • Database: books.sqlite
  • Configuration: *.config files

Additional Features

Automatic Scanning

For Linux/macOS, you can configure a cron job:

# Add to crontab
0 3 * * * mono /path/to/TinyOPDSCLI.exe scan

Working Behind Proxy/NAT

For internet access:

  1. Configure port forwarding on router
  2. Use dynamic DNS service
  3. Or set up reverse proxy (nginx/Apache)

Known Limitations

  • macOS GUI: Native GUI not supported due to Mono WinForms limitations. Use CLI or Wine.
  • Large libraries: Initial scan of 500,000+ books may take several hours depending on hardware.
  • Memory usage: Approximately 1 GB RAM per 200,000 books during scanning.

Clone this wiki locally