Repository navigation
Setup_en
-
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
-
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 | 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.
- Download the latest version from GitHub Releases
- Extract the archive to any folder
- For Windows 7 SP1, 8, 8.1 - install .NET Framework 4.8 if not present
- 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.
Ubuntu/Debian:
sudo apt update
sudo apt install mono-completeFedora/CentOS/RHEL:
sudo dnf install mono-completeArch Linux:
sudo pacman -S monoopenSUSE:
sudo zypper install mono-complete# Make the file executable
chmod +x TinyOPDS.exe
# Run via Mono
mono TinyOPDS.exeImportant: The GUI version does not work natively on macOS due to WinForms incompatibility with 64-bit Mono. You have three options:
- Use the CLI version (recommended)
- Use Wine to run the GUI version
- Configure settings on Windows/Linux and copy the config file
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 sqliteRunning CLI Version:
# Navigate to program folder
cd /path/to/tinyopds
# Scan library
mono TinyOPDSCLI.exe scan
# Start server
mono TinyOPDSCLI.exe startSQLite Note: macOS system SQLite has compatibility issues with Mono.Data.Sqlite. Installing SQLite via Homebrew resolves crashes during scanning.
# 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/TinyOPDSWine allows running the Windows version on Linux and macOS with full GUI functionality.
Linux:
# Ubuntu/Debian
sudo apt install wine wine32
# Fedora
sudo dnf install wine
# Arch
sudo pacman -S winemacOS:
brew install --cask wine-stable# 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 &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):
- Open Automator
- Create new Application
- Add "Run Shell Script" action
- Enter:
cd /path/to/tinyopds && wine TinyOPDS.exe 2>/dev/null - Save as TinyOPDS.app
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.
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 uninstallWindows service features:
- Installed with automatic startup (delayed-auto)
- Runs under LocalSystem
- Recovery policy configured (restart on failure)
- Logs saved to
TinyOPDS.logfile in program folder
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 uninstallDuring 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.targetFile locations:
- Data:
/var/lib/tinyopds/ - Logs:
/var/log/tinyopds/ - Configuration: in program folder
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)
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 uninstallWhen 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/
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
- Start TinyOPDS (GUI or CLI)
- For GUI: Go to "Scanner" tab
- Specify path to books folder
- Click "Start scanning" or use
mono TinyOPDSCLI.exe scan
- For GUI: Go to "Server" tab
- If your computer has multiple network cards, select the appropriate network interface
- Set port (default 8080)
- 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.
Open a browser and navigate to:
- Local access:
http://localhost:8080/ - Network:
http://[your-ip]:8080/ - OPDS catalog:
http://[your-ip]:8080/opds
Recommendation: For the console version, first configure all settings via the GUI version, then copy the
TinyOPDS.configfile to the folder withTinyOPDSCLI.exe. If both executable files are in the same folder, they automatically use the shared configuration file.
- Settings:
TinyOPDS.config - Database:
books.sqlitein program folder - Logs:
TinyOPDS.login program folder
- Settings:
TinyOPDS.config - Database:
books.sqlitein program folder - Program logs:
TinyOPDS.login program folder - Service logs:
/var/log/tinyopds/(Linux) or~/Library/Logs/TinyOPDS/(macOS)
- Stop the service/program
- Save a copy of the
books.sqlitedatabase - Replace program files with new version
- Start the program/service
The database is compatible between versions and requires no conversion.
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:
- Use the CLI version (fully functional)
- Run GUI version with Wine
- Configure on Windows/Linux and copy the config file
If you experience crashes during scanning on macOS, install Homebrew's SQLite:
brew install sqliteThis resolves compatibility issues between Mono.Data.Sqlite and macOS system SQLite.
Windows:
# Check service status
sc query TinyOPDS
# View logs in Event Viewer
eventvwr.mscLinux:
# For systemd
sudo systemctl status tinyopds
sudo journalctl -u tinyopds -f
# For init.d
sudo service tinyopds status
tail -f /var/log/tinyopds/*.logmacOS:
# 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/*.logChange the port in settings or find the process using the port:
# Linux/macOS
lsof -i :8080
# Windows
netstat -ano | findstr :8080- Use SSD for database
- Perform initial scan on a powerful computer
- Copy ready database to target device
- Use HTTP authorization ("Auth" tab)
- Configure firewall to restrict access by IP
- Use VPN for remote access
Regularly save copies of:
- Database:
books.sqlite - Configuration:
*.configfiles
For Linux/macOS, you can configure a cron job:
# Add to crontab
0 3 * * * mono /path/to/TinyOPDSCLI.exe scanFor internet access:
- Configure port forwarding on router
- Use dynamic DNS service
- Or set up reverse proxy (nginx/Apache)
- 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.