Attempted modernizing of SC-Docker networking and debugging#93
Open
KarlIsWright wants to merge 9 commits intoGames-and-Simulations:masterfrom
Open
Attempted modernizing of SC-Docker networking and debugging#93KarlIsWright wants to merge 9 commits intoGames-and-Simulations:masterfrom
KarlIsWright wants to merge 9 commits intoGames-and-Simulations:masterfrom
Conversation
- Update Docker networking to use sc_net bridge network with isolation disabled - Add comprehensive debug mode with strace and tcpdump monitoring - Add privileged networking capabilities for better LAN discovery - Modernize Wine base from Ubuntu 18.04/Wine 2.x to Ubuntu 22.04/Wine 6.x - Add configurable BWAPI settings via environment variables - Add debug container with X11 desktop and debugging tools - Using --debug flag uses special debug container and implies --log_level DEBUG & --log_verbose - Fix headless mode display issues with proper Xvfb setup - Add hook scripts for runtime configuration and debugging - Improve error handling and logging throughout
Summary\n\nThis commit addresses stability and LAN connectivity issues observed when running StarCraft in containers (especially under rootless Podman).\n\nKey changes\n\n- Xvfb auth removal:\n - Remove "-auth ~/.Xauthority" from all Xvfb invocations to avoid referencing a non-existent .Xauthority file that prevented the virtual display from starting reliably.\n - Applied to docker/scripts/play_common.sh and the debug image startup script.\n\n- Wine/winetricks networking stack:\n - Install DirectPlay and related networking components (wininet, winhttp, urlmon) into the Wine prefix using winetricks.\n - Run winetricks under xvfb-run during build to avoid DISPLAY issues.\n - Add cabextract as a winetricks dependency.\n\n- Debug image hardening:\n - Add cabextract to dbg image.\n - Execute optional patch scripts conditionally (tolerate forks without these scripts).\n - Ensure winetricks networking components are preinstalled in the dbg image as well.\n\n- Runtime/container options:\n - Grant NET_BIND_SERVICE in addition to NET_RAW and NET_ADMIN.\n - Restrict "privileged" to debug mode only (kept with seccomp=unconfined for tooling).\n\n- Misc:\n - Avoid running the hello-world container as part of ensure_docker_can_run() to reduce unnecessary side effects.\n\nFiles changed\n\n- docker/dockerfiles/wine.dockerfile\n - Add cabextract.\n - Install wine32 + winetricks and preinstall DirectPlay/wininet/winhttp/urlmon (via xvfb-run).\n\n- docker/dockerfiles/dbg.dockerfile\n - Add cabextract.\n - Make patch scripts optional and robust if missing.\n - Preinstall DirectPlay & other networking libs via winetricks (xvfb-run).\n - Remove -auth from Xvfb in the dbg startup flow.\n\n- docker/scripts/play_common.sh\n - Remove -auth ~/.Xauthority from both headless and GUI Xvfb startups; keep logs directed to files when LOG_GUI is enabled.\n\n- scbw/docker_utils.py\n - Add NET_BIND_SERVICE in cap_add; only use privileged in --debug.\n - Comment out hello-world check in ensure_docker_can_run().\n\nWhy\n\n- Xvfb would fail to start in certain environments because the referenced .Xauthority did not exist inside the container; removing -auth makes the display reliable and unblocks Wine GUI apps.\n- StarCraft LAN relies on legacy DirectPlay; without installing it in the Wine prefix, LAN mode could stall or fail.\n- Rootless Podman needs extra care with capabilities and privileges. This change narrows default privileges and enables extended privileges only when explicitly debugging.\n\nNotes\n\n- Rootless NAT (pasta / slirp4netns) still limits L2 broadcast discovery; "direct IP join" via bwheadless (e.g., --lan-sendto) remains the recommended workaround under rootless setups.\n
Added cross-platform safety for chmod operations and comprehensive Podman usage guide Changes: - Made chmod operations cross-platform safe by wrapping in try/except blocks - Added platform detection for debug logging - Created comprehensive PODMAN.md documentation covering installation, network configuration, LAN multiplayer workarounds, known issues, and troubleshooting The chmod operations now gracefully handle Windows environments where Unix permissions have no effect on mounted volumes
This commit represents significant work on debugging capabilities and
investigation into Docker networking limitations for StarCraft LAN play.
Key Changes:
============
1. Debug Container Improvements:
- Removed automatic debugging processes from debug containers
- Debug containers now start exactly like game containers
- All debugging tools available via manual 'docker exec' commands
- Added comprehensive DEBUG.md documentation
2. Container Runtime Detection:
- Improved Docker/Podman runtime detection in docker_utils.py
- Support for rootful/rootless detection
- Better socket-based runtime discovery
3. UDP Networking Tools:
- Added hook_init.sh for UDP relay initialization
- Created separate UDP testing scripts:
* udp_broadcast_receiver.sh - Listen for broadcasts
* udp_broadcast_sender.sh - Send test broadcasts
* udp_relay_manual.sh - Manual relay control
- Fixed port conflicts in UDP relay implementation
4. Build System Fixes:
- Fixed docker/build_images.sh for rootful Docker
- Removed registry push attempts
- Better build order handling
5. Documentation:
- Added DEBUG.md with complete debugging guide
- Added NETWORK_FINDINGS.md documenting UDP broadcast limitations
- Extensive testing results and analysis
Known Issues:
=============
- Docker blocks UDP broadcasts between containers (all network types)
- StarCraft LAN discovery relies on UDP broadcasts to 255.255.255.255
- Current UDP relay scripts provide partial workaround only
Future Work:
============
- Investigate BWAPI source modification for unicast discovery
- Explore external relay service on host
- Consider alternative container runtimes
This commit establishes a solid foundation for debugging and documents
the fundamental limitations we've discovered with Docker networking.
This commit reorganizes all debug-specific scripts for better clarity and maintainability. Changes Made: ============= 1. Script Organization: - Moved all debug-specific scripts to docker/scripts/debug/ - Added DEBUG_ prefix to clearly identify container scripts - Kept production scripts in docker/scripts/ unchanged 2. Renamed Scripts (with DEBUG_ prefix): - auto_debug_startup.sh → DEBUG_auto_startup.sh - internal_network_analysis.sh → DEBUG_network_analysis.sh - internal_network_debug.sh → DEBUG_network_debug.sh - patch_debug_gui.sh → DEBUG_patch_gui.sh - patch_play_common.sh → DEBUG_patch_play_common.sh - udp_broadcast_receiver.sh → DEBUG_udp_receiver.sh - udp_broadcast_sender.sh → DEBUG_udp_sender.sh - udp_relay_manual.sh → DEBUG_udp_relay.sh 3. Updated References: - docker/dockerfiles/dbg.dockerfile: Updated COPY paths - DEBUG.md: Updated all script references - NETWORK_FINDINGS.md: Updated script paths - UPSTREAM_ISSUE.md: Created comprehensive issue documentation Benefits: ========= - Clear separation between production and debug scripts - DEBUG_ prefix makes it obvious which scripts are in containers - Easier to maintain and understand the codebase - No functional changes, purely organizational Testing Scripts: ================ The debug/test_*.sh scripts remain for host-side testing and are not copied into containers. These help validate networking setups before deployment. Documentation: ============== Added UPSTREAM_ISSUE.md with detailed analysis of the UDP broadcast limitation in Docker, ready to submit to the upstream repository. This reorganization maintains backward compatibility while providing a cleaner structure for future development.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR improves the StarCraft Docker environment with several key enhancements:
Networking Changes
Debugging Features
Wine Environment Modernization
BWAPI Enhancements
General Improvements
Remaining Issues
This is because default podmad rootless containers do not support broadcast/multicast
These changes bring update packages, and significant debugging improvements.