qt6-migration-pipeline/external-dependencies/offline-cache/README.md

# Offline Package Cache for Air-Gapped Environment

> **Important:** This directory is excluded from version control (`.gitignore`). The offline cache must be built separately on a machine with internet access, then transferred to the air-gapped environment via secure media or artifact repository.

This directory contains all external dependencies required for building the Legatus project in an air-gapped (offline) environment.

## Directory Structure

```
offline-cache/
├── qt6/                    # Qt 6.10.2 installation (2.2GB, 12,320 files)
│   └── 6.10.2/
│       └── gcc_64/
│           └── lib/cmake/Qt6/
│
├── src/                    # Source tarballs for custom builds
│   ├── KDReports-2.3.0.tar.gz      (8.3MB)
│   ├── Log4Qt-2.0.0.tar.gz         (1.0MB)
│   └── grantlee-20d415b.tar.gz     (2.5MB)
│
├── deb/                    # Ubuntu 26.04 development packages (49 packages, 51MB)
│   ├── build-essential_*.deb
│   ├── cmake_*.deb
│   ├── libqt6*.deb
│   ├── libboost-dev_*.deb
│   ├── libssl-dev_*.deb
│   └── ... (46 more)
│
├── scripts/                # Offline installation scripts
│   ├── install-offline.sh  # Main installation script
│   └── package-list.txt    # Complete package inventory
│
└── README.md               # This file
```

## Contents Summary

| Component | Size | Files | Description |
|-----------|------|-------|-------------|
| Qt 6.10.2 | 2.2GB | 12,320 | Complete Qt installation (gcc_64) |
| Source Tarballs | 12MB | 3 | KDReports, Log4Qt, Grantlee |
| Ubuntu .deb | 51MB | 49 | Development packages |
| **Total** | **2.3GB** | **12,372** | Complete offline cache |

## Usage in Air-Gapped Environment

### 1. Copy to Air-Gapped System

Transfer the entire `offline-cache/` directory to your air-gapped build system:

```bash
# On connected system
tar -czf offline-cache.tar.gz offline-cache/

# Transfer via secure medium (USB, secure transfer, etc.)

# On air-gapped system
tar -xzf offline-cache.tar.gz
```

### 2. Install Qt 6.10.2

```bash
# Copy Qt installation to target location
cp -r offline-cache/qt6/6.10.2 /opt/Qt/

# Set environment variables
export Qt6_DIR=/opt/Qt/6.10.2/gcc_64
export PATH=$Qt6_DIR/bin:$PATH
```

### 3. Install Ubuntu Development Packages

```bash
# Install all .deb packages
cd offline-cache/deb
sudo dpkg -i *.deb

# Or use apt with local repository
cd offline-cache/deb
sudo apt install ./*.deb
```

### 4. Build Custom Dependencies

```bash
# KDReports
cd /tmp
tar -xzf offline-cache/src/KDReports-2.3.0.tar.gz
cd KDReports-2.3.0
mkdir build && cd build
cmake -DCMAKE_PREFIX_PATH=/opt/Qt/6.10.2/gcc_64 ..
make -j8
sudo make install

# Log4Qt
cd /tmp
tar -xzf offline-cache/src/Log4Qt-2.0.0.tar.gz
cd Log4Qt-2.0.0
mkdir build && cd build
cmake -DCMAKE_PREFIX_PATH=/opt/Qt/6.10.2/gcc_64 ..
make -j8
sudo make install

# Grantlee
cd /tmp
tar -xzf offline-cache/src/grantlee-20d415b.tar.gz
cd grantlee-20d415b
mkdir build && cd build
cmake -DGRANTLEE_BUILD_WITH_QT6=ON -DCMAKE_PREFIX_PATH=/opt/Qt/6.10.2/gcc_64 ..
make -j8
sudo make install
```

### 5. Verify Installation

```bash
# Check Qt version
qmake6 --version

# Check CMake
cmake --version

# Check compilers
g++ --version
clang++ --version
```

## Package Inventory

### Qt Components (6.10.2)
- Qt Base (Core, Gui, Widgets, Network, etc.)
- Qt SVG
- Qt Concurrent
- Qt Test
- Qt Linguist Tools

### Ubuntu Development Packages (49 total)
- **Build Tools:** build-essential, cmake, clang, gcc, g++
- **Qt6 Libraries:** libqt6core6, libqt6gui6, libqt6widgets6, libqt6svg6, etc.
- **Development Headers:** libqt6-dev, libqt6svg6-dev, libkf6texttemplate-dev
- **Database:** libpq-dev, postgresql-server-dev-all
- **Testing:** libgtest-dev, libgmock-dev
- **Security:** libssl-dev, libbotan-3-dev
- **Multimedia:** libvlc-dev, vlc-plugin-base
- **Other:** libboost-dev, libgeographiclib-dev, libpoppler-qt6-dev, libxml2-dev, libicu-dev

### Source Tarballs
- **KDReports 2.3.0:** Report generation library
- **Log4Qt 2.0.0:** Logging framework
- **Grantlee (20d415b):** String template library

## Jenkins Integration

The offline cache is used by Jenkins pipelines in air-gapped environments:

```groovy
// In Jenkinsfile
stage('Setup Offline Dependencies') {
    steps {
        script {
            // Copy offline cache to build workspace
            sh 'cp -r /path/to/offline-cache ${WORKSPACE}/'
            
            // Install Qt
            sh 'cp -r ${WORKSPACE}/offline-cache/qt6/6.10.2 /opt/Qt/'
            
            // Install .deb packages
            sh 'cd ${WORKSPACE}/offline-cache/deb && sudo dpkg -i *.deb'
            
            // Build custom dependencies
            sh 'bash ${WORKSPACE}/offline-cache/scripts/install-offline.sh'
        }
    }
}
```

## Maintenance

### Updating Dependencies

To update the offline cache:

1. Run the download script on a connected system:
   ```bash
   cd external-dependencies
   bash scripts/download-all-dependencies.sh ./offline-cache
   ```

2. Verify the downloaded packages:
   ```bash
   bash scripts/verify-offline-cache.sh ./offline-cache
   ```

3. Transfer to air-gapped system

### Verification Checklist

- [ ] Qt 6.10.2 installation complete (12,320+ files)
- [ ] All source tarballs present (KDReports, Log4Qt, Grantlee)
- [ ] All 49 .deb packages downloaded
- [ ] Package list matches inventory
- [ ] Installation scripts tested

## Troubleshooting

### Qt Installation Issues
- Ensure correct architecture (gcc_64 for x86_64)
- Check CMAKE_PREFIX_PATH includes Qt directory
- Verify Qt6_DIR environment variable

### Package Installation Issues
- Check Ubuntu version matches (26.04)
- Ensure all dependencies are satisfied
- Use `dpkg --configure -a` to fix broken installs

### Build Issues
- Verify all custom dependencies are installed
- Check CMake can find Qt6 components
- Ensure compiler toolchain is complete

## License Compliance

All packages include their respective licenses:
- Qt 6.10.2: LGPL v3 / Commercial
- KDReports: Apache 2.0
- Log4Qt: Apache 2.0
- Grantlee: BSD 2-Clause
- Ubuntu packages: Various (see individual .deb files)

SBOM (Software Bill of Materials) is generated by the CI/CD pipeline using `generate-sbom.sh`.

## Contact

For questions or issues with the offline cache, refer to:
- `external-dependencies/DEPENDENCIES-INVENTORY.md` - Complete dependency list
- `external-dependencies/AIRGAP-SUMMARY.md` - Air-gap configuration
- Jenkins pipeline documentation