RdpBroker/web-gateway/BUILD-ARM64.md

Building for Raspberry Pi 4 (ARM64)

Quick Start

The web-gateway is fully compatible with Raspberry Pi 4 running K3s! 🎉

Option 1: Build Multi-Arch Image (Recommended)

Build once, run on both x86_64 and ARM64:

chmod +x build-multiarch.sh

# Build and push to Docker Hub
IMAGE_NAME=yourusername/web-gateway IMAGE_TAG=1.0.0 ./build-multiarch.sh

# Or use default (easylinux/web-gateway:latest)
./build-multiarch.sh

Option 2: Build ARM64 Only

Faster if you only need ARM64:

chmod +x build-arm64.sh

# Build for ARM64
IMAGE_NAME=yourusername/web-gateway IMAGE_TAG=1.0.0 ./build-arm64.sh

# Push to registry
docker push yourusername/web-gateway:1.0.0

Option 3: Build Natively on Raspberry Pi

Build directly on your RPi 4 (slower but simpler):

# On your Raspberry Pi 4
docker build -t yourusername/web-gateway:1.0.0 .
docker push yourusername/web-gateway:1.0.0

Deploy to K3s on Raspberry Pi

# Update values.yaml or use --set
helm install rdp-web-gateway ./chart/rdp-web-gateway \
  --namespace rdpbroker \
  --create-namespace \
  --set image.repository=yourusername/web-gateway \
  --set image.tag=1.0.0 \
  --set service.type=ClusterIP \
  --set traefik.enabled=true \
  --set traefik.host=rdp.yourdomain.com \
  --set traefik.tls.enabled=true \
  --set traefik.tls.certResolver=letsencrypt

Resource Recommendations for Raspberry Pi 4

The default values.yaml may be too high for RPi 4. Use this configuration:

# values-rpi4.yaml
resources:
  limits:
    cpu: 500m      # Down from 1000m
    memory: 512Mi  # Down from 1Gi
  requests:
    cpu: 100m      # Down from 200m
    memory: 128Mi  # Down from 256Mi

autoscaling:
  enabled: true
  minReplicas: 1   # Down from 2 (save memory)
  maxReplicas: 3   # Down from 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80

replicaCount: 1    # Start with 1 replica

Deploy with adjusted resources:

helm install rdp-web-gateway ./chart/rdp-web-gateway \
  --namespace rdpbroker \
  -f chart/rdp-web-gateway/examples/traefik-letsencrypt.yaml \
  -f values-rpi4.yaml

Performance Notes

• Node.js Alpine images are very lightweight (~50MB compressed)
• Memory footprint: ~100-200MB per pod under normal load
• CPU usage: Very low when idle, spikes during RDP streaming
• Network: WebSocket is efficient, ~1-5Mbps per active session
• Recommended: 2-4GB RAM Raspberry Pi 4 can handle 3-5 concurrent sessions

Verify Architecture

After building, verify the image supports ARM64:

docker buildx imagetools inspect yourusername/web-gateway:1.0.0

Expected output:

MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest:    sha256:...
           
Manifests:
  Name:      linux/amd64
  Digest:    sha256:...
  Platform:  linux/amd64
           
  Name:      linux/arm64
  Digest:    sha256:...
  Platform:  linux/arm64

Troubleshooting

Image pull fails on ARM64

# Check current architecture
uname -m  # Should show: aarch64

# Verify image manifest
docker manifest inspect yourusername/web-gateway:1.0.0 | grep architecture

OOMKilled (Out of Memory)

Reduce memory limits or number of replicas:

resources:
  limits:
    memory: 256Mi  # Lower if needed
autoscaling:
  minReplicas: 1

Build too slow

• Use build-arm64.sh instead of build-multiarch.sh
• Build on Raspberry Pi 4 itself (native build)
• Use GitHub Actions or CI/CD to build multi-arch images

GitHub Actions Example

Add .github/workflows/build.yml:

name: Build Multi-Arch

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v2
        
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2
        
      - name: Login to DockerHub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
          
      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: ./web-gateway
          platforms: linux/amd64,linux/arm64
          push: true
          tags: |
            yourusername/web-gateway:latest
            yourusername/web-gateway:${{ github.ref_name }}

Additional Notes

• K3s on RPi 4: Works perfectly! K3s is optimized for ARM
• Storage: Use SSD instead of SD card for better I/O performance
• Network: Gigabit Ethernet recommended for RDP streaming
• Cooling: Consider a fan/heatsink for sustained load