BC Docker Manager: An Electron + Next.js Desktop App for Business Central Containers

Overview

Microsoft's BcContainerHelper is a great PowerShell module — until Windows 11 24H2 broke it with persistent HNS port conflicts. Rather than wait for a fix, this Electron app routes around the problem entirely: it talks to Docker directly, detects the specific HNS errors that 24H2 throws, and runs a one-click recovery sequence. It's also a perfectly capable container manager: list, create, start, stop, remove, view logs, run backups, and ask Claude what went wrong when something does.

Stack

• Desktop: Electron 35
• Frontend: Next.js 16 (App Router), React, TypeScript
• Styling: Tailwind CSS with custom theme
• Build: electron-builder (Windows installer + portable)
• Testing: Jest + React Testing Library
• Deployment: Electron Builder (local Windows app)

Key Features

• BC Docker container management (list, create, start, stop, remove)
• Container creation wizard with one-click deployment
• Real-time log viewing
• Backup and restore operations (PowerShell-based)
• AI-powered troubleshooting chat (Claude API)
• HNS (Host Network Service) error detection and automated recovery
• Network diagnostics panel (orphaned endpoints, NAT mappings, port conflicts)
• PowerShell script execution with real-time output streaming
• Two deployment paths: direct Docker (primary) and BcContainerHelper (legacy)

Three-Layer Architecture

1. Main Process (electron/main.js) — window management, IPC, PowerShell execution.
2. Preload Script (electron/preload.js) — secure bridge between main and renderer.
3. Frontend (Next.js App Router) — client components with a lib/electron-api.ts abstraction.

Dual API Mode

• Electron Mode — uses IPC via window.electronAPI for Docker, backup, and AI operations.
• Web Mode (fallback) — uses Next.js API routes via fetch.

This lets the same UI run in a browser for development without an Electron shell.

Container Naming

The app filters for containers matching the bcserver-* pattern. Anything else is hidden from the dashboard — keeps general Docker containers on the host out of the way.

Deployment Scripts

HNS Error Detection & Recovery

lib/hns-error-detector.ts parses PowerShell output for the specific error signatures Windows 11 24H2 surfaces:

• Port Conflicts (0x803b0013)
• HNS Endpoint Errors
• NAT Mapping Conflicts
• Service Failures

Recovery flow: error detected → HNSErrorRecovery component shown → Run Diagnostics → Clean HNS State → Retry Deployment. Roughly 90% of HNS failures clear on the first sweep.

Settings

Persistent settings live in %APPDATA%/bc-container-manager/settings.json:

Routes

Building for Distribution

npm run build                    # Build Next.js static export
npm run electron:build:win       # Build Windows installer
npm run electron:build:portable  # Build portable .exe

Output:

• Installer: dist/BC Container Manager-Setup-1.0.0.exe
• Portable: dist/BC Container Manager-Portable-1.0.0.exe

Requires icon files in assets/: icon.ico (Windows), icon.png (512x512).

Lessons Learned

• BcContainerHelper fails on Windows 11 24H2 with persistent HNS 0x803b0013 errors — direct docker commands are more reliable.
• shell.openExternal should be restricted to http/https only — anything else is a vector.
• Settings updates need a whitelist on the main-process side. Don't let the renderer write arbitrary keys.
• The Windows elevation dialog must respect Cancel. Treat user refusal as a real outcome, not an error to retry past.
• Password fields need metacharacter checks before they hit a PowerShell command line.
• PowerShell scripts touching HNS cmdlets require Administrator. Plan for the elevation prompt.
• Docker Desktop must be running — surface that as a startup health check, not an obscure error twenty clicks deep.

CI/CD

build-test.yml runs on a Windows runner with Node 20: type-check → tests → electron:pack. ci.yml does lint and build checks. release.yml automates releases.