# 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 (creates .dmg)
npm run build:mac

# Linux (creates AppImage and .deb)
npm run build:linux
```

### Build Output

Built applications are placed in the `dist/` directory:

- **Windows**: `dist/win-unpacked/DashCaddy Installer.exe` (portable)
- **macOS**: `dist/DashCaddy Installer.dmg`
- **Linux**: `dist/DashCaddy Installer.AppImage` and `.deb`

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