tqma6-yocto-mirror/docs/04-deployment/corporate-network-deployment.md

# Corporate Network Deployment Guide

**Document ID:** DEPLOY-CORP-001  
**Date:** 2026-03-01  
**Environment:** Corporate network (potentially air-gapped)  
**Prerequisites:** Approved software mirror archive

---

## Overview

This guide describes the deployment of the Yocto mirror and build environment within a corporate network after software approval has been obtained.

**Assumptions:**
- Software approval has been granted
- Mirror archive has been transferred securely to corporate network
- Target system: Ubuntu 22.04 LTS (or approved corporate Linux)
- Internet access: May be restricted or unavailable

---

## Pre-Deployment Checklist

Before starting deployment:

- [ ] Software approval documentation received
- [ ] Mirror archive transferred (USB/secure file transfer)
- [ ] Checksum verified: `sha256sum -c archive.tar.gz.sha256`
- [ ] Sufficient disk space available (200GB+)
- [ ] Corporate Ubuntu 22.04 system ready
- [ ] User has sudo privileges

---

## Step 1: Extract Mirror Archive

```bash
# Create base directory
export CORP_BASE=/opt/tqma6-yocto
sudo mkdir -p ${CORP_BASE}
sudo chown $(whoami):$(whoami) ${CORP_BASE}

# Extract mirror archive
cd ${CORP_BASE}
tar xzf /path/to/transfer/tqma6-yocto-mirror-scarthgap-*.tar.gz

# Verify structure
ls -la mirror-package/
# Should show: sources/, licenses/, downloads/, build-instructions/
```

---

## Step 2: Install Build Dependencies

### 2.1 From Corporate Repository

```bash
# Update package lists
sudo apt update

# Install required packages (from approved corporate repos)
sudo apt install -y \
    gawk wget git diffstat unzip texinfo gcc build-essential \
    chrpath socat cpio python3 python3-pip python3-pexpect \
    xz-utils debianutils iputils-ping python3-git \
    python3-jinja2 libegl1-mesa libsdl1.2-dev xterm \
    locales lz4 zstd rpcsvc-proto
```

**Note:** If packages are not available, request them from IT department.

### 2.2 Locale Configuration

```bash
sudo locale-gen en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
```

---

## Step 3: Setup Yocto Build Environment

### 3.1 Create Directory Structure

```bash
cd ${CORP_BASE}

# Create working directories
mkdir -p build
mkdir -p mirror

# Copy sources
cp -r mirror-package/sources/* ./

# Setup downloads directory (offline)
mkdir -p downloads
cp -r mirror-package/downloads/* downloads/ 2>/dev/null || true
```

### 3.2 Initialize Build

```bash
# Source the build environment
cd ${CORP_BASE}/poky-scarthgap
source oe-init-build-env ${CORP_BASE}/build

# You are now in ${CORP_BASE}/build
```

### 3.3 Configure for Offline Build

Edit `${CORP_BASE}/build/conf/local.conf`:

```conf
# Machine selection
MACHINE ??= "tqma6ulx-mba6ulx"

# Offline/Premirror configuration
BB_NO_NETWORK = "1"

# Use local mirror for all sources
PREMIRRORS:prepend = " \
    git://.*/.* file://${CORP_BASE}/downloads/ \
    ftp://.*/.* file://${CORP_BASE}/downloads/ \
    http://.*/.* file://${CORP_BASE}/downloads/ \
    https://.*/.* file://${CORP_BASE}/downloads/ \
"

# Don't check for updates
BB_FETCH_PREMIRRORONLY = "1"

# Parallelism
BB_NUMBER_THREADS ?= "8"
PARALLEL_MAKE ?= "-j8"

# DL directory
DL_DIR = "${CORP_BASE}/downloads"

# SSTATE (optional, for faster rebuilds)
SSTATE_DIR = "${CORP_BASE}/sstate-cache"

# Archive settings for compliance
INHERIT += "archiver"
ARCHIVER_MODE[src] = "original"
COPY_LIC_MANIFEST = "1"
COPY_LIC_DIRS = "1"
```

### 3.4 Configure Layers

Edit `${CORP_BASE}/build/conf/bblayers.conf`:

```conf
BBLAYERS ?= " \
  ${CORP_BASE}/poky-scarthgap/meta \
  ${CORP_BASE}/poky-scarthgap/meta-poky \
  ${CORP_BASE}/poky-scarthgap/meta-yocto-bsp \
  ${CORP_BASE}/meta-openembedded/meta-oe \
  ${CORP_BASE}/meta-openembedded/meta-python \
  ${CORP_BASE}/meta-openembedded/meta-networking \
  ${CORP_BASE}/meta-openembedded/meta-filesystems \
  ${CORP_BASE}/meta-tq/meta-tq \
  "
```

---

## Step 4: Build Image

### 4.1 First Build (Offline)

```bash
cd ${CORP_BASE}/build

# Ensure we're in the build environment
source ${CORP_BASE}/poky-scarthgap/oe-init-build-env ${CORP_BASE}/build

# Start build (all sources should be local)
bitbake core-image-minimal
```

**Expected:** Build completes without network access.

### 4.2 Verify 2038 Compliance

After successful build:

```bash
# Check time_t size in generated toolchain
${CORP_BASE}/build/tmp/sysroots/x86_64-linux/usr/bin/arm-poky-linux-gnueabi-gcc -dM -E - < /dev/null | grep TIME_BITS
# Expected: #define __TIME_BITS 64

# Check kernel config
bitbake -e virtual/kernel | grep CONFIG_COMPAT_32BIT_TIME
# Expected: CONFIG_COMPAT_32BIT_TIME=y
```

---

## Step 5: Development Workflow

### 5.1 Daily Use

```bash
# Enter build environment
cd ${CORP_BASE}
source poky-scarthgap/oe-init-build-env build

# Build target
bitbake core-image-minimal

# Deploy to target (SD card / eMMC)
# See TQ documentation for deployment methods
```

### 5.2 Adding Custom Layers

If custom corporate layers are required:

```bash
# Add to bblayers.conf
vim ${CORP_BASE}/build/conf/bblayers.conf

# Add path to custom layer
# ${CORP_BASE}/meta-custom \
```

### 5.3 SDK Generation

For application development:

```bash
# Generate SDK
bitbake core-image-minimal -c populate_sdk

# Install SDK
${CORP_BASE}/build/tmp/deploy/sdk/*.sh

# Source SDK environment
source /opt/poky/.../environment-setup-arm-poky-linux-gnueabi
```

---

## Maintenance

### Updating the Mirror

When new TQ BSP versions are approved:

1. Request updated mirror from external system
2. Verify checksums
3. Extract to separate directory
4. Compare with current deployment
5. Test build in isolation
6. Switch over after validation

### Build Cache Management

```bash
# Clean build (keep downloads)
bitbake -c cleanall core-image-minimal

# Full clean (careful!)
rm -rf ${CORP_BASE}/build/tmp/
```

---

## Troubleshooting

### Issue: Network timeout errors

**Cause:** BitBake trying to fetch from internet

**Solution:**
```bash
# Verify BB_NO_NETWORK is set
grep BB_NO_NETWORK ${CORP_BASE}/build/conf/local.conf

# Should show: BB_NO_NETWORK = "1"
```

### Issue: Missing source files

**Cause:** Incomplete mirror transfer

**Solution:**
```bash
# Check downloads directory
ls ${CORP_BASE}/downloads | wc -l
# Compare with external mirror

# Re-transfer missing files
```

### Issue: Permission denied

**Solution:**
```bash
# Fix ownership
sudo chown -R $(whoami):$(whoami) ${CORP_BASE}
```

---

## Security Considerations

1. **No Internet Access:** Build must complete without network
2. **Audit Trail:** All sources archived and version-controlled
3. **License Compliance:** License manifest generated for every build
4. **User Permissions:** Build as regular user, not root

---

## Validation Checklist

- [ ] Mirror extracted and verified
- [ ] Offline build successful
- [ ] 2038 compliance verified (64-bit time_t)
- [ ] License manifest generated
- [ ] Image deploys to target hardware
- [ ] SDK functional for application development

---

## Support

For issues:
1. Check [TQ BSP Documentation](https://github.com/tq-systems/meta-tq)
2. Review Yocto Project manuals (included in mirror)
3. Consult internal engineering team

---

**Author:** Siggi ⚙️  
**Date:** 2026-03-01  
**Classification:** Internal Use