Cleanup repo + harden offline install and watchdog

Repo hygiene: - Remove dead scripts (.wait-for-display, .display-keepalive, .keep-screen-alive) - Remove stale backup/scratch (install.sh.bak, New.txt, stale .pyc) - Stop tracking machine-specific/generated state (config/app_config.json, playlists/server_playlist.json, src/player_auth.json, generated launchers) - Prune duplicate wheel versions (one per package) - Reorganize working_files -> dev/, dev/tests/, documentation/dev-notes/, scripts/ - Extend .gitignore; fix no-op rules in repo/.gitignore Offline install (install.sh): - Non-fatal system-dep step; per-package apt retry; .deb bundle install - Skip pip self-upgrade offline; guard online fallbacks behind connectivity probe - Dependency-free fetch_url (curl/wget/urllib); --no-reboot flag - Fix corrupted literal backslash-bang escapes (shebangs, test -f, banner) - Idempotent cron install (no more stacked @reboot lines) Autostart / watchdog: - start.sh: single-instance flock lock (.player_watchdog.lock) acquired only after a display is confirmed, preventing parallel watchdogs - Set XDG_RUNTIME_DIR when missing; exit early if headless - run_player.sh: activate .venv; stop_player.sh: clear lock file
2026-10-14 23:29:14 +03:00
parent f7b889be11
commit 31807f37bf
60 changed files with 633 additions and 1469 deletions
@@ -0,0 +1,159 @@
+# Offline Installation Guide
+
+This guide explains how to set up and use offline installation for the Kiwy Signage Player.
+
+## Overview
+
+The offline installation system allows you to install the signage player on devices without internet access by pre-downloading all necessary packages.
+
+## Directory Structure
+
+```
+Kiwy-Signage/
+├── repo/                          # Offline packages repository
+│   ├── python-wheels/            # Python packages (.whl files)
+│   ├── system-packages/          # System package information
+│   │   ├── apt-packages.txt     # List of required apt packages
+│   │   └── debs/                # Downloaded .deb files (optional)
+│   └── README.md
+├── scripts/
+│   ├── download_offline_packages.sh  # Download Python packages
+│   └── download_deb_packages.sh      # Download system .deb packages
+└── install.sh                    # Smart installer (online/offline)
+```
+
+## Setup for Offline Installation
+
+### Step 1: Prepare on a Connected System
+
+On a system with internet access (preferably Raspberry Pi OS):
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd Kiwy-Signage
+
+# Download Python packages
+bash scripts/download_offline_packages.sh
+
+# (Optional) Download system .deb packages
+bash scripts/download_deb_packages.sh
+```
+
+This will populate the `repo/` folder with all necessary packages.
+
+### Step 2: Transfer to Offline System
+
+Copy the entire `Kiwy-Signage` directory to your offline system:
+
+```bash
+# Using USB drive
+cp -r Kiwy-Signage /media/usb/
+
+# Or create a tarball
+tar -czf kiwy-signage-offline.tar.gz Kiwy-Signage/
+
+# On target system, extract:
+tar -xzf kiwy-signage-offline.tar.gz
+cd Kiwy-Signage
+```
+
+### Step 3: Install on Offline System
+
+The installer automatically detects offline packages:
+
+```bash
+# Automatic detection
+bash install.sh
+
+# Or explicitly specify offline mode
+bash install.sh --offline
+```
+
+## Package Information
+
+### Python Packages (requirements.txt)
+
+- **kivy==2.1.0** - UI framework
+- **requests==2.32.4** - HTTP library
+- **bcrypt==4.2.1** - Password hashing
+- **aiohttp==3.9.1** - Async HTTP client
+- **asyncio==3.4.3** - Async I/O framework
+
+### System Packages (APT)
+
+See `repo/system-packages/apt-packages.txt` for complete list:
+- Python development tools
+- SDL2 libraries (video/audio)
+- FFmpeg and codecs
+- GStreamer plugins
+- Build dependencies
+
+## Online Installation
+
+If you have internet access, simply run:
+
+```bash
+bash install.sh
+```
+
+The installer will automatically download and install all packages from the internet.
+
+## Updating Offline Packages
+
+To update the offline package cache:
+
+```bash
+# On a connected system
+bash scripts/download_offline_packages.sh
+```
+
+This will download the latest versions of all packages.
+
+## Troubleshooting
+
+### Problem: Missing Dependencies
+
+If installation fails due to missing dependencies:
+
+```bash
+# Download .deb packages with dependencies
+bash scripts/download_deb_packages.sh
+
+# Install with dependency resolution
+sudo apt install -f
+```
+
+### Problem: Wheel Not Found
+
+If a specific Python package wheel is not found:
+
+```bash
+# Download specific package
+pip3 download <package-name> -d repo/python-wheels/
+```
+
+### Problem: Architecture Mismatch
+
+Ensure packages are downloaded on the same architecture (ARM for Raspberry Pi):
+
+```bash
+# Verify architecture
+uname -m  # Should show: armv7l or aarch64
+
+# Force ARM downloads
+pip3 download -r requirements.txt -d repo/python-wheels/ --platform linux_armv7l
+```
+
+## Storage Requirements
+
+- **Python wheels**: ~50-100 MB
+- **System .deb packages**: ~200-500 MB (if downloaded)
+- **Total**: ~250-600 MB
+
+## Notes
+
+- The `repo/` folder is designed to be portable
+- Downloaded packages are excluded from git (see `.gitignore`)
+- The installer supports both online and offline modes seamlessly
+- System packages list is maintained in `repo/system-packages/apt-packages.txt`