Commonwealth-Online-Server/DEPLOYMENT.md

Commonwealth Online GUI - Deployment Guide

Quick Start - Running the GUI

First Time Setup (Deploy Qt DLLs)

The executable needs Qt6 runtime libraries. Deploy them once:

cd host-gui
deploy.bat

This copies all required Qt6 DLLs and plugins to the Release folder.

Running the Application

After deployment, simply:

# Double-click this file:
build/bin/Release/CommonwealthOnlineHost.exe

# Or run from command line:
cd build/bin/Release
CommonwealthOnlineHost.exe

---

Distribution

To distribute the application to other machines:

Option 1: Copy Entire Folder (Easiest)

Release/
├── CommonwealthOnlineHost.exe
├── Qt6Core.dll
├── Qt6Gui.dll
├── Qt6Widgets.dll
├── Qt6Network.dll
├── Qt6Concurrent.dll
├── Qt6DBus.dll
├── Qt6Xml.dll
└── plugins/
    ├── platforms/
    ├── styles/
    └── imageformats/

Just zip and send this folder - everything needed is included.

Option 2: Use Qt Deployment Tool (Advanced)

Qt provides windeployqt.exe for automatic deployment:

C:\Qt\6.11.1\msvc2022_64\bin\windeployqt.exe build/bin/Release/CommonwealthOnlineHost.exe

---

Requirements for Users

Recipients of the .exe need only:

• Windows 10 or later
• Python 3.9+ (for running the relay server)
• No Visual Studio or Qt installation needed

---

Troubleshooting

"Entry point not found" error

The DLLs weren't deployed. Run:

deploy.bat

"The procedure entry point... could not be located"

Likely a missing or incompatible DLL. Try redeploying:

# Clean old DLLs
del build\bin\Release\*.dll

# Redeploy
deploy.bat

Application window doesn't appear

The GUI may have launched but is hidden. Check:

1. Task Manager for CommonwealthOnlineHost.exe process
2. Try running from command line to see error messages
3. Ensure Python and server directory are accessible

---

Development Build vs Release Build

For Development:

# Just build (DLLs not deployed)
build.bat

For Distribution:

# Build + deploy DLLs
build.bat
deploy.bat

---

Next Steps

1. Test Locally

   • Run CommonwealthOnlineHost.exe
   • Click "Start Server"
   • Run fake_client.py from server folder
   • Verify client appears in table

2. Package for Release

   • Run deploy.bat
   • Zip build/bin/Release/ folder
   • Distribute to users

3. Create Installer (Future Enhancement)

   • Use NSIS or WiX to create .msi installer
   • Automatically handles DLL deployment
   • Adds Start Menu shortcuts
   • Enables uninstall

---

File Locations

host-gui/
├── CMakeLists.txt           # Build configuration
├── build.bat                # Compile application
├── deploy.bat               # Deploy Qt DLLs ← Run this after build.bat
├── check-setup.bat          # Verify prerequisites
├── find-qt.bat              # Locate Qt6 installation
├── README.md                # User guide
├── SETUP.md                 # Setup instructions
├── src/                     # Source code
└── build/
    └── bin/
        └── Release/
            ├── CommonwealthOnlineHost.exe
            ├── Qt6*.dll                    # Runtime libraries
            └── plugins/                    # Qt plugins

---

Creating a Portable Distribution

Windows Host GUI (unchanged)

To create a self-contained package anyone can run:

# Build the application from the repository root
build.bat

# Deploy DLLs
deploy.bat

# Create distribution package
# (build.bat / deploy.bat already stage server\ next to the exe)
mkdir Commonwealth-Online-Host
xcopy /I /E build\bin\Release Commonwealth-Online-Host\
copy README.md Commonwealth-Online-Host\README.txt

# Zip and distribute
# Send Commonwealth-Online-Host.zip to users

Users extract and run CommonwealthOnlineHost.exe - no setup needed! Target machines still need Python 3.9+ on PATH for the bundled relay server.

Linux dedicated server packaging

Prefer a .tar.gz archive of the server/ directory so the executable bit on start.sh is retained.

Do not include:

• server/.venv/
• server/__pycache__/
• server/logs/
• local runtime files such as operator-specific bans.json unless intentional

Example:

tar --exclude='.venv' --exclude='__pycache__' --exclude='logs' \
  --exclude='*.pyc' -czf commonwealth-online-server-linux.tar.gz -C server .

If you also ship a ZIP archive, document that some extraction tools may drop Unix executable permissions. Recipients can recover with:

sed -i 's/\r$//' start.sh
chmod +x start.sh
./start.sh

Windows Host GUI packaging remains ZIP-based and is unchanged by the Linux packaging guidance above.

---

Support

If users encounter issues:

1. Ensure deployment completed successfully (see output)
2. Verify Python is installed and in PATH
3. Check that server\ exists next to the executable (contains consumer_server_cli.py)
4. Run from command line to see detailed error messages

---

Performance Notes

• Startup time: <1 second
• Memory usage: ~80-150 MB
• CPU: Minimal (event-driven)
• DLL size: ~100-150 MB total (but only loaded once)

Deploy once, run forever! 🚀