Hermes
af970aa564
Adds scripts/build-dmg-linux.sh + 'npm run build:dmg': - virt-make-fs creates an HFS+ volume inside a plain 400M image file (guestfs appliance; never touches block devices) - libdmg-hfsplus converts it to compressed UDZO .dmg (real koly/UDIF) - app + /Applications drag-install symlink; secret scan on extracted contents - BUILD_GUIDE documents the route + Gatekeeper first-run note Verified end-to-end: rc=0, 121MB DMG with valid koly trailer, extractall round-trip reproduced the full 264MB app, secrets scan clean.
306 lines
8.3 KiB
Markdown
306 lines
8.3 KiB
Markdown
# 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 <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:
|
|
|
|
```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 <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:
|
|
|
|
```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
|