# DashCaddy Installer - Build Guide ## Overview The DashCaddy Installer is a cross-platform Electron application that guides users through installing and configuring DashCaddy on their system. ## Prerequisites - Node.js 18+ and npm - Git - Windows: No additional requirements - macOS: Xcode Command Line Tools - Linux: Standard build tools (gcc, make) ## Installation ```bash # Clone the repository cd dashcaddy-installer # Install dependencies npm install ``` ## Development ### Run in Development Mode ```bash # Start the installer with DevTools npm run dev # Or start normally npm start ``` ### Run Tests ```bash # Run all tests npm test # Run tests in watch mode npm run test:watch ``` ## Building ### Build for Current Platform ```bash npm run build ``` ### Build for Specific Platforms ```bash # Windows (creates portable .exe and installer) npm run build:win # macOS zip (from any host; electron-builder's native target) npm run build:mac # macOS real drag-install .dmg — built ON LINUX, no Mac needed # (one-time toolchain: see scripts/build-dmg-linux.sh header) npm run build:dmg # Linux (creates AppImage and .deb) npm run build:linux ``` ### Build Output Built applications are placed in the `build-output/` directory: - **Windows**: `build-output/DashCaddy Installer .exe` (portable) and `build-output/DashCaddy Installer Setup .exe` (NSIS installer) — filenames embed the current `version` from package.json - **macOS**: `build-output/DashCaddy Installer--mac.zip` — the configured mac target is `zip` (unsigned; signed builds require a Mac with signing credentials). `npm run build:dmg` additionally produces a real drag-install `build-output/DashCaddy Installer-.dmg` built entirely on Linux (libguestfs HFS+ volume + libdmg-hfsplus UDZO compression; unsigned — macOS Gatekeeper will show the standard right-click→Open dialog on first launch) - **Linux**: `build-output/DashCaddy Installer-.AppImage` and `build-output/dashcaddy-installer__amd64.deb` ### Cross-platform build requirements (verified 2026-09-01) Building Windows installers from Linux requires **wine with both 64-bit and 32-bit support** — NSIS's 32-bit post-processing runs under wine: ```bash # Ubuntu 24.04 (Debian/Ubuntu package names; other distros vary). # Requires root / sudo for the dpkg and apt steps. dpkg --add-architecture i386 # add i386 mirror entries if the main sources are amd64-only pinned apt-get update && apt-get install -y wine64 wine32:i386 # initialize a prefix once (avoids kernel32.dll load failures in CI) export WINEPREFIX=~/.wine-dashcaddy && wineboot --init ``` Without wine32, the NSIS setup exe is built but ends up as a ~211KB stub (payload not appended) and the build appears to pass (exit 0). Check the result — the size (~90MB+) is a quick heuristic, but the **authoritative** check is listing/extracting the payload: ```bash 7z l "build-output/DashCaddy Installer Setup .exe" # should list a large app-64.7z # or extract and scan: 7z x && 7z x '$PLUGINSDIR/app-64.7z' ``` After every build, run the secrets scanner to verify no private key material was bundled into the shipped resources: ```bash npm run build:scan ``` ## Project Structure ``` dashcaddy-installer/ ├── src/ │ ├── main/ # Electron main process │ │ ├── index.js # Main entry point & IPC handlers │ │ ├── dependency-checker.js # Check/install Docker & Caddy │ │ ├── config-manager.js # Configuration persistence │ │ ├── file-deployer.js # Copy dashboard & API files │ │ ├── caddyfile-generator.js # Generate Caddyfile │ │ ├── browser-launcher.js # Open URLs in browser │ │ └── service-manager.js # Start/stop services │ ├── renderer/ # UI layer │ │ ├── index.html # Main HTML │ │ ├── wizard.js # Wizard logic & state │ │ └── styles.css # Styling │ ├── preload/ # IPC bridge │ │ └── index.js # Secure IPC exposure │ └── shared/ # Shared utilities │ ├── constants.js # App constants │ └── platform-utils.js # Platform detection ├── templates/ # Configuration templates │ ├── Caddyfile.template # Caddyfile template │ └── docker-compose.template.yml ├── assets/ # Images & icons │ └── icon.png # App icon └── package.json # Dependencies & build config ``` ## Key Features ### 1. Platform Detection Automatically detects Windows, macOS, or Linux and adjusts paths and commands accordingly. ### 2. Dependency Management - Checks for Docker and Caddy installation - Provides installation instructions/automation - Validates versions ### 3. Guided Installation 5-step wizard: 1. **Welcome** - Introduction and platform detection 2. **Folders** - Select installation directories 3. **Dependencies** - Check and install requirements 4. **Install** - Deploy files and configure 5. **Complete** - Success screen with dashboard link ### 4. File Deployment - Copies dashboard files from `status/` directory - Copies API server from `dashcaddy-api/` directory - Installs npm dependencies for API - Skips unnecessary files (node_modules, .git) ### 5. Configuration Generation - Creates Caddyfile for reverse proxy - Generates docker-compose.yml for API container - Saves installation configuration for upgrades ### 6. Service Management - Starts Caddy web server - Launches Docker containers - Opens dashboard in browser when ready ## Configuration ### Build Configuration Edit `package.json` under the `build` section: ```json { "build": { "appId": "com.dashcaddy.installer", "productName": "DashCaddy Installer", "icon": "assets/icon.png", "win": { "target": ["portable", "dir"] } } } ``` ### Source Paths The installer copies files from these source directories (relative to project root): - Dashboard: `../status/` - API Server: `../dashcaddy-api/` These paths are configured in `src/main/file-deployer.js`. ## Troubleshooting ### Build Fails 1. **Missing dependencies**: Run `npm install` 2. **Electron download fails**: Check internet connection or use `npm config set electron_mirror https://npmmirror.com/mirrors/electron/` 3. **Icon errors**: Ensure `assets/icon.png` exists and is valid ### Installer Doesn't Start 1. **Check Node version**: Must be 18+ 2. **Reinstall dependencies**: `rm -rf node_modules && npm install` 3. **Check console**: Run with `npm run dev` to see errors ### Files Not Deploying 1. **Check source paths**: Verify `status/` and `dashcaddy-api/` directories exist 2. **Check permissions**: Ensure write access to installation directory 3. **Check disk space**: Ensure sufficient space for installation ## Testing ### Unit Tests Tests are located in `src/main/*.test.js`: ```bash npm test ``` ### Property-Based Tests Some modules include property-based tests using fast-check: ```bash npm test -- --testNamePattern="property" ``` ### Manual Testing 1. Run installer: `npm start` 2. Go through all wizard steps 3. Verify files are copied correctly 4. Check that services start 5. Confirm dashboard opens in browser ## Deployment ### Creating a Release 1. Update version in `package.json` 2. Build for all platforms: ```bash npm run build:win npm run build:mac npm run build:linux ``` 3. Test each build on target platform 4. Create GitHub release with built artifacts ### Distribution - **Windows**: Distribute `.exe` file (portable, no installation required) - **macOS**: Distribute `.dmg` file - **Linux**: Distribute `.AppImage` (universal) or `.deb` (Debian/Ubuntu) ## Advanced ### Custom Branding Replace `assets/icon.png` with your custom icon (512x512 PNG recommended). ### Custom Templates Edit templates in `templates/` directory to customize generated configurations. ### Adding New Steps 1. Add step definition to `wizard.js` steps array 2. Create render function (e.g., `renderMyStep()`) 3. Add case to `renderCurrentStep()` switch 4. Update navigation logic if needed ## Support For issues or questions: - Check existing documentation - Review console logs with `npm run dev` - Check GitHub issues ## License MIT