Kiwy-Signage/OFFLINE_INSTALLATION.md

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
├── 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):

# Clone the repository
git clone <repository-url>
cd Kiwy-Signage

# Download Python packages
bash download_offline_packages.sh

# (Optional) Download system .deb packages
bash 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:

# 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:

# 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 install.sh

The installer will automatically download and install all packages from the internet.

Updating Offline Packages

To update the offline package cache:

# On a connected system
bash download_offline_packages.sh

This will download the latest versions of all packages.

Troubleshooting

Problem: Missing Dependencies

If installation fails due to missing dependencies:

# Download .deb packages with dependencies
bash 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:

# 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):

# 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