dashcaddy/dashcaddy-installer/BUILD_GUIDE.md

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

# Clone the repository
cd dashcaddy-installer

# Install dependencies
npm install

Development

Run in Development Mode

# Start the installer with DevTools
npm run dev

# Or start normally
npm start

Run Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

Building

Build for Current Platform

npm run build

Build for Specific Platforms

# 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 <version>.exe (portable) and build-output/DashCaddy Installer Setup <version>.exe (NSIS installer) — filenames embed the current version from package.json
• macOS: build-output/DashCaddy Installer-<version>-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-<version>.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-<version>.AppImage and build-output/dashcaddy-installer_<version>_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:

# 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:

7z l "build-output/DashCaddy Installer Setup <version>.exe"   # should list a large app-64.7z
# or extract and scan: 7z x <setup.exe> && 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:

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:

{
  "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:

npm test

Property-Based Tests

Some modules include property-based tests using fast-check:

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:

   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