Add offline dependency download scripts for air-gapped environment

- download-all-dependencies.sh: Downloads Qt6 6.10.2, source tarballs, and Ubuntu .deb packages - download-deb-packages.sh: Downloads Ubuntu .deb packages in Docker container - verify-offline-cache.sh: Verifies offline cache completeness - offline-cache/README.md: Documentation for offline cache structure and usage - .gitignore: Exclude external-dependencies/offline-cache/ from version control (2.3GB) The offline cache must be transferred to air-gapped environment via secure media. Excluded from git due to size and security best practices. Co-authored-by: Copilot <2235566219+Copilot@users.noreply.github.com> Entire-Checkpoint: 01M6PFZM0GHMBF46BKYPKZC192
2026-11-05 18:36:48 +00:00
1 parent 733c7b40d1
commit 242a21c521
@@ -0,0 +1,238 @@
+# 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