qt6-migration-pipeline/external-dependencies/EXTERNAL-DEPENDENCIES-README.md

# External Dependencies CI/CD Pipelines

This directory contains CI/CD pipelines for 8 external dependencies required for the Legatus project in air-gapped environments.

## Overview

| Dependency | Version | License Type | Pipeline Status |
|------------|---------|--------------|-----------------|
| AVS | 1.0.0 | Contract-based (lifetime) | ✅ Complete |
| ArcGIS | 300.0.0 | Embedded ini-file licenses (lifetime) | ✅ Complete |
| BuildingModels | 1.0.0 | Proprietary | ✅ Complete |
| GeographicLib | 1.52 | MIT | ✅ Complete |
| Schusstafel | 1.0.0 | Proprietary | ✅ Complete |
| dtEntity | 1.0.0 | Open Source | ✅ Complete |
| RTI Connext DDS | 7.7.0 | Commercial license file (lifetime) | ✅ Complete |
| tmsif | 1.0.0 | Contract-based (lifetime) | ✅ Complete |

## Directory Structure

```
external-dependencies/
├── avs/                    # AVS dependency pipeline
│   ├── Dockerfile
│   └── Jenkinsfile
├── arcgis/                 # ArcGIS Runtime SDK pipeline
│   ├── Dockerfile
│   └── Jenkinsfile
├── buildingmodels/         # BuildingModels dependency pipeline
│   ├── Dockerfile
│   └── Jenkinsfile
├── geographiclib/          # GeographicLib dependency pipeline
│   ├── Dockerfile
│   └── Jenkinsfile
├── schusstafel/            # Schusstafel dependency pipeline
│   ├── Dockerfile
│   └── Jenkinsfile
├── dtentity/               # dtEntity game engine pipeline
│   ├── Dockerfile
│   └── Jenkinsfile
├── rti-connext-dds/        # RTI Connext DDS pipeline
│   ├── Dockerfile
│   └── Jenkinsfile
├── tmsif/                  # TMSIF dependency pipeline
│   ├── Dockerfile
│   └── Jenkinsfile
├── scripts/
│   ├── generate-sbom.sh    # SBOM generation script
│   ├── download-all-dependencies.sh
│   ├── download-deb-packages.sh
│   └── verify-offline-cache.sh
├── offline-cache/          # Downloaded packages (excluded from git)
├── DEPENDENCIES-INVENTORY.md
├── AIRGAP-SUMMARY.md
└── README.md
```

## License Handling

### RTI Connext DDS (File-Based)
- **License File:** `rti_license.dat` (repository root)
- **Type:** FlexLM commercial license
- **Handling:** 
  - License file copied into container during build
  - `RTI_LICENSE_FILE` environment variable set
  - Jenkinsfile copies license from repository root to build context
- **Location in Container:** `/opt/rti_license.dat`

### AVS (Contract-Based)
- **Type:** Lifetime license contract
- **Handling:** No license file required
- **Notes:** License managed at contract level, not file-based

### ArcGIS (Embedded Ini-File Licenses)
- **Type:** Map-specific embedded licenses
- **Handling:** Licenses embedded in 19 `.ini` files
- **Location:** `Lts/Viewer/SituationMap/Map/*.ini`
- **Notes:** Licenses travel with map configuration files

### tmsif (Contract-Based)
- **Type:** Lifetime license contract
- **Handling:** No license file required
- **Notes:** License managed at contract level, not file-based

### Other Dependencies
- **BuildingModels, Schusstafel:** Proprietary, contract-based
- **GeographicLib:** MIT license (open source)
- **dtEntity:** Open source

## Air-Gapped Environment Configuration

All Dockerfiles include:
- Internal Nexus repository: `remote-repo.sl.defence-elec.de:8081`
- Proxy configuration: `http://10.198.80.130:3128`
- Harbor registry: `harbor.sl.defence-elec.de/proxydockerhub`
- Internal CA certificates
- User creation (ctc, rme)

## SBOM Generation

All pipelines generate:
- CycloneDX SBOM (`sbom.json`)
- SLSA provenance (`provenance.json`)
- License report (`licenses.txt`)

SBOM files are stored in `sbom/` subdirectory for each dependency.

## Usage

### Building a Specific Dependency

```bash
cd external-dependencies/<dependency-name>
docker build -t <image-name>:<version> .
```

### Running Jenkins Pipeline

1. Ensure offline cache is available at `/opt/offline-cache/`
2. Configure Harbor credentials in Jenkins
3. Run pipeline from respective Jenkinsfile

### Offline Installation

For air-gapped environments:
1. Run `scripts/download-all-dependencies.sh` in connected environment
2. Transfer `offline-cache/` via secure media (encrypted USB)
3. Mount offline cache in Jenkins container
4. Pipelines will use cached packages

## Verification

Each pipeline includes verification stage:
- AVS: Checks `/opt/AVS/` directory
- ArcGIS: Verifies SDK installation and directory structure
- RTI: Validates license file and environment variable
- Others: Verify installation directories and basic functionality

## Troubleshooting

### License Issues (RTI)
- Ensure `rti_license.dat` is in repository root
- Check `RTI_LICENSE_FILE` environment variable in container
- Verify license server connectivity (if using network license)

### Offline Cache Issues
- Verify cache structure: `qt6/`, `src/`, `deb/`
- Check file permissions in mounted volumes
- Ensure all required packages are downloaded

### Build Failures
- Check proxy configuration in Dockerfile
- Verify internal repository accessibility
- Review CA certificate installation

## Security Considerations

- License files (e.g., `rti_license.dat`) excluded from git via `.gitignore`
- Offline cache (2.3GB) excluded from version control
- Transfer sensitive files via encrypted media only
- Harbor credentials managed via Jenkins credentials store
- All containers run as non-root user (ctc)

## Related Documentation

- `DEPENDENCIES-INVENTORY.md` - Complete dependency inventory
- `AIRGAP-SUMMARY.md` - Air-gapped environment adaptation details
- `offline-cache/README.md` - Offline cache structure and usage
- `scripts/README.md` - Script documentation