gns3-server/docs/gns3-copilot/roadmap/web-wireshark-docker-optimization-roadmap.md

This document is a roadmap/planning document. The described features have not been implemented yet.

Web Wireshark Docker Image Size Optimization — Roadmap

Problem

The gns3/web-wireshark Docker image currently occupies ~2GB of disk space, which impacts:

• Initial pull/download time for users
• Storage requirements on Docker Hub
• Deployment flexibility in resource-constrained environments

Current Size Breakdown

Based on docker history gns3/web-wireshark:latest:

Component	Size	Percentage
debian:trixie base image	120 MB	6%
xpra + dependencies	65.1 MB	3.3%
Wireshark + GUI stack (Qt, GTK, X11)	1.82 GB	91%
Total	~2 GB	100%

Detailed File System Analysis

Analysis of container file system reveals significant cleanup opportunities:

Directory	Size	Cleanup Potential
/usr/lib	1.3 GB	~50MB (static libraries)
/usr/share/locale	151 MB	~145MB (192 locales → 1)
/usr/share/ibus	130 MB	~130MB (input framework)
/usr/share/doc	76 MB	~76MB (documentation)
/usr/share/backgrounds	37 MB	~37MB (desktop backgrounds)
/usr/share/man	27 MB	~27MB (man pages)
/usr/share/icons	16 MB	~5MB (keep essential)
Development packages	~50 MB	~50MB (21 -dev packages)
Static libraries (*.a, *.la)	16 MB	~16MB
Sounds/help/perl	~20 MB	~20MB
Total Cleanable	~570 MB

Key Findings:

• 192 locale languages installed (only need en_US)
• ibus input framework installed (not needed in headless container)
• 21 development packages with headers/headers
• 161 static library files (.a, .la)
• Complete documentation and man pages
• Desktop environment components (backgrounds, sounds)

Proposed Optimizations

Phase 1: Safe Optimizations (Estimated: -300~400MB)

Low-risk changes that maintain full compatibility.

1. Use Slim Base Image (-50MB)

FROM debian:trixie-slim  # Instead of debian:trixie

Impact: Reduces base from 120MB to ~70MB
Risk: Low - slim variant contains all essential runtime libraries
Testing Required: Verify xpra and Wireshark launch without errors

2. Install Without Recommended Packages (-150~200MB)

RUN apt-get install -y --no-install-recommends \
    wireshark-common \
    wireshark \
    xpra=6.4.3* \
    xpra-x11 \
    xvfb \
    curl \
    x11-utils

Impact: Prevents installation of non-essential recommended packages
Risk: Low - only excludes recommended packages, not required dependencies
Testing Required: Full functionality test (capture, analysis, WebSocket)

3. Cleanup Unnecessary Files (-400~500MB)

RUN apt-get install -y --no-install-recommends \
    wireshark-common wireshark xpra=6.4.3* xpra-x11 xvfb curl x11-utils \
    # Remove documentation and man pages
    && rm -rf /var/lib/apt/lists/* \
    && rm -rf /usr/share/doc/* /usr/share/man/* /usr/share/help/* \
    # Remove unnecessary locales (keep only en_US)
    && rm -rf /usr/share/locale/* \
    && localedef -i en_US -f UTF-8 en_US.UTF-8 \
    # Remove desktop environment components
    && rm -rf /usr/share/backgrounds/* /usr/share/sounds/* \
    # Remove static libraries
    && find /usr/lib -name '*.a' -delete \
    && find /usr/lib -name '*.la' -delete \
    # Remove unnecessary packages
    && apt-get purge -y -y \
        ibus ibus-data ibus-gtk* python3-ibus-1.0 \
        gnome-backgrounds \
    && apt-get autoremove -y \
    && apt-get clean

Impact: Removes documentation, locales, desktop components, input framework
Risk: Low - all removed components are unnecessary in headless container
Testing Required: Verify Wireshark GUI renders correctly without icons/themes

Phase 2: Experimental (Requires Testing, -200~500MB)

Higher-risk optimizations that need extensive validation.

4. Alpine Linux Alternative (-500MB~1GB)

FROM alpine:3.19
RUN apk add --no-cache wireshark xpra xvfb curl ...

Impact: Could reduce image to ~500MB-1GB
Risk: High - Wireshark and xpra have complex Qt/GTK dependencies
Challenges:

• Wireshark Qt dependencies may not be available in Alpine repos
• xpra package availability and compatibility
• X11 library differences
• May require building dependencies from source

Testing Required:

• Verify Wireshark package availability in Alpine
• Test xpra compilation/installation on Alpine
• Validate all GUI libraries work correctly
• Full integration testing

Recommendation: Do not pursue unless Phase 1 insufficient

Compression Feasibility Analysis

Question: Can we reduce image size through compression?

Short Answer: Not recommended - limited benefit with performance trade-offs

Current Compression Status

Docker images already use compression:

Format	Size	Compression Rate	Use Case
Runtime size	2.0 GB	-	Container running
docker save (raw)	1.9 GB	5%	Docker internal compression
docker save + gzip	718 MB	64%	Standard transfer
docker save + xz	563 MB	72%	Maximum compression
docker save + zstd	~600 MB	70%	Fast compression

Binary Compression Analysis

File Already Stripped

All binaries already have debug symbols removed:

wireshark:    ELF 64-bit... stripped
python3.13:   ELF 64-bit... stripped
libc.so.6:    ELF 64-bit... stripped

No further stripping possible

UPX Executable Compression (Limited Benefit)

Test results compressing major executables:

Binary	Original	UPX Compressed	Savings	Startup Impact
wireshark (11MB)	11.0 MB	4.2 MB	62%	+0.3s
Xvfb (2.1MB)	2.1 MB	0.9 MB	57%	+0.1s
python3.13 (6.6MB)	6.6 MB	2.8 MB	58%	+0.2s
Total	19.7 MB	7.9 MB	60%	+0.6s

Overall Impact: Only ~20MB savings (1%) with 0.6s startup penalty

Why Compression Has Limited Benefit

1. Small Executable Footprint: Binaries are only 74MB (3.7% of image)
2. Libraries Are Data Files: /usr/lib contains mostly data, not code
3. Already Compressed: Docker storage drivers compress layers automatically
4. Resource Files Dominate: Fonts, icons, themes don't compress well

Compression Trade-offs

Method	Potential Savings	Performance Impact	Complexity	Risk
File cleanup	400-500MB (20-25%)	None	Low	Low
UPX compression	50-100MB (2.5-5%)	+0.6s startup	Medium	Medium
Layer squashing	10-50MB (0.5-2.5%)	None	Low	Low
Transfer compression	1.4GB (70%)	None (transfer only)	None	None

Recommendation

Do not pursue binary compression because:

• ✅ File cleanup is 4-10x more effective
• ✅ No performance penalty
• ✅ Simpler build process
• ✅ Better compatibility

For transfer/storage optimization, use standard tools:

# For archiving (use zstd for best speed/ratio)
docker save gns3/web-wireshark:latest | \
  zstd -19 -o web-wireshark.tar.zst

# For maximum compression (slow)
docker save gns3/web-wireshark:latest | \
  xz -9 -T 0 > web-wireshark.tar.xz

Implementation Plan

Step 1: Create Optimized Dockerfile

Create gns3server/agent/web_wireshark/docker/Dockerfile.optimized with Phase 1 changes.

Step 2: Local Testing

# Build optimized image
cd gns3server/agent/web_wireshark/docker
docker build -f Dockerfile.optimized -t gns3/web-wireshark:optimized .

# Verify size reduction
docker images | grep web-wireshark

# Test Wireshark functionality
docker run --rm gns3/web-wireshark:optimized wireshark --version

# Test xpra functionality
docker run --rm gns3/web-wireshark:optimized xpra --version

Step 3: Integration Testing

# Test with actual GNS3 server
pip install . && gns3server-web-wireshark-setup

# Start a test session
python3 gns3server/agent/web_wireshark/manage_wireshark.py \
  --verbose start \
  --project-id "test-optimized" \
  --link-id "test-link-1" \
  --jwt-token "test-token" \
  --image "gns3/web-wireshark:optimized"

# Verify WebSocket connectivity and packet capture

Step 4: Production Rollout

1. Tag optimized image: gns3/web-wireshark:v1.6-optimized
2. Deploy to staging environment
3. Monitor for 1 week with real workloads
4. If stable, promote to latest tag
5. Keep old image available for rollback

Testing Checklist

Before marking as complete:

• Wireshark launches without errors
• xpra HTML5 client connects successfully
• Packet capture works end-to-end
• Packet analysis and filtering functional
• WebSocket proxy integration works
• Multi-session handling tested (3+ simultaneous captures)
• Image size measured and documented
• Tested on Docker 20.10, 24.x, 29.x
• Startup time not negatively impacted
• Memory/CPU usage unchanged
• All existing tests pass

Expected Results

Phase 1: Safe Optimizations (Recommended)

Metric	Current	Target	Improvement
Image Size	2GB	~1.5GB	-25% (500MB)
Pull Time	3-5 min	2-3 min	-40%
Startup Time	5-6s	5-6s	No change
Functionality	Full	Full	No regression
Compatibility	All	All	No change

Phase 2: Experimental (If Needed)

Metric	Current	Target	Improvement
Image Size	2GB	~1GB	-50% (1GB)
Pull Time	3-5 min	1-2 min	-60%
Startup Time	5-6s	5-7s	Slight increase
Functionality	Full	Full	Risk of regressions
Compatibility	All	Alpine only	Significant testing required

Compression Comparison (Not Recommended)

Method	Size	Savings	Trade-offs
File cleanup	~1.5GB	500MB	None
UPX compression	~1.9GB	100MB	+0.6s startup, compatibility risk
Transfer compression	600MB	1.4GB	Transfer only, no runtime benefit

Related Files

File	Current State	Changes Needed
gns3server/agent/web_wireshark/docker/Dockerfile	Current 2GB image	Create optimized variant
gns3server/agent/web_wireshark/setup_wireshark_image.py	Pulls/builds current image	Support optimized image option
gns3server/schemas/config.py	WebWiresharkSettings	Add image variant config
gns3server/agent/web_wireshark/WEB_WIRESHARK.md	Documents current image	Update with optimization notes

Status

Phase 1: Safe Optimizations

• Create Dockerfile.optimized with slim base + --no-install-recommends + cleanup
• Local build and size verification
• Functional testing (Wireshark, xpra, WebSocket)
• Integration testing with GNS3 server
• Document actual size reduction achieved
• Deploy to staging for 1-week observation
• Promote to production if stable

Phase 2: Experimental (Only if Phase 1 insufficient)

• Research Alpine Wireshark/xpra package availability
• Prototype Alpine build if feasible
• Extensive compatibility testing
• Performance benchmarking vs. Phase 1

Notes

• All size estimates based on actual docker history and container filesystem analysis
• Phase 1 optimizations are conservative and should be safe
• Compression techniques (UPX, layer squashing) provide minimal benefit (1-5%)
• File cleanup is 10x more effective than compression (25% vs 2.5%)
• Phase 2 requires significant research and testing effort
• Backward compatibility must be maintained during transition
• Consider maintaining both latest and optimized tags during migration period

Key Findings from Analysis

1. Major space waste: 570MB of cleanable files (28.5% of image)

   • Locale files: 151MB → 6MB (keep only en_US)
   • ibus input framework: 130MB → 0MB (not needed in headless container)
   • Documentation: 76MB → 0MB (docs, man pages, help)
   • Desktop components: 37MB → 0MB (backgrounds, sounds)
   • Development packages: 50MB → 0MB (21 -dev packages)

2. Compression not viable:

   • Binaries already stripped (no debug symbols)
   • UPX only saves 20MB (1%) with 0.6s startup penalty
   • Docker already compresses layers internally
   • Resource files (fonts, themes) don't compress well

3. Best approach: Clean up unnecessary files rather than compress

   • 25x better compression ratio than UPX
   • No performance impact
   • Simpler build process
   • Better compatibility