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

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

```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 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 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`