dashcaddy/dashcaddy-installer/README.md

# DashCaddy Installer

A cross-platform Electron application that provides a guided installation wizard for DashCaddy - the unified management platform for Docker containers and Caddy reverse proxy.

## ✨ Features

- **🎯 Guided 5-Step Wizard** - Simple, intuitive installation process
- **🔍 Automatic Dependency Detection** - Checks for Docker and Caddy
- **📦 One-Click Dependency Installation** - Installs missing requirements
- **🖥️ Cross-Platform Support** - Windows, macOS, and Linux
- **📁 Smart File Deployment** - Copies and configures all necessary files
- **⚙️ Auto-Configuration** - Generates Caddyfile and docker-compose.yml
- **🚀 Service Management** - Starts services and opens dashboard
- **💾 Configuration Persistence** - Saves settings for upgrades
- **🎨 Modern UI** - Clean, responsive interface with progress tracking

## 🚀 Quick Start

### For End Users

1. **Download** the installer for your platform
2. **Run** the executable (portable, no installation needed)
3. **Follow** the wizard steps
4. **Access** your dashboard at http://localhost:8080

See [QUICK_START.md](QUICK_START.md) for detailed user instructions.

### For Developers

```bash
# Install dependencies
npm install

# Run in development mode with DevTools
npm run dev

# Build for Windows
npm run build:win
```

See [BUILD_GUIDE.md](BUILD_GUIDE.md) for comprehensive build instructions.

## 📋 System Requirements

- **Operating System**: Windows 10/11, macOS 10.15+, or Linux
- **RAM**: 4GB minimum, 8GB recommended
- **Disk Space**: 2GB free space
- **Dependencies**: Docker and Caddy (installer can install these)

## 🏗️ Project Structure

```
dashcaddy-installer/
├── src/
│   ├── main/                      # Electron main process
│   │   ├── index.js              # Main entry & IPC handlers
│   │   ├── dependency-checker.js # Docker/Caddy detection
│   │   ├── config-manager.js     # Configuration management
│   │   ├── file-deployer.js      # File copying & deployment
│   │   ├── caddyfile-generator.js # Config generation
│   │   ├── browser-launcher.js   # Browser integration
│   │   └── service-manager.js    # Service control
│   ├── renderer/                  # UI layer
│   │   ├── index.html            # Main HTML
│   │   ├── wizard.js             # Wizard logic
│   │   └── 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
│   └── README.md
├── assets/                        # Images & icons
│   ├── icon.png                  # App icon
│   └── dashcaddy-logo.png
├── dist/                          # Build output (generated)
├── BUILD_GUIDE.md                 # Comprehensive build guide
├── QUICK_START.md                 # User quick start guide
└── package.json                   # Dependencies & config
```

## 🛠️ Development

### Setup

```bash
# Clone the repository
git clone <repository-url>
cd dashcaddy-installer

# Install dependencies
npm install
```

### Running

```bash
# Development mode with DevTools
npm run dev

# Production mode
npm start
```

### Testing

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run property-based tests
npm test -- --testNamePattern="property"
```

### Building

```bash
# Build for current platform
npm run build

# Build for specific platforms
npm run build:win    # Windows
npm run build:mac    # macOS
npm run build:linux  # Linux
```

**Build Output:**
- Windows: `dist/win-unpacked/DashCaddy Installer.exe` (168MB portable)
- macOS: `dist/DashCaddy Installer.dmg`
- Linux: `dist/DashCaddy Installer.AppImage`

## 📖 Documentation

- **[BUILD_GUIDE.md](BUILD_GUIDE.md)** - Complete build and development guide
- **[QUICK_START.md](QUICK_START.md)** - User installation guide
- **[templates/README.md](templates/README.md)** - Template documentation

## 🎯 Installation Wizard Steps

### 1. Welcome
- Introduction to DashCaddy
- Platform detection
- Feature overview

### 2. Choose Folders
- Select installation directory
- Configure Docker data path
- Set Caddy config location

### 3. Check Dependencies
- Detect Docker installation
- Detect Caddy installation
- Install missing dependencies

### 4. Installation
- Deploy dashboard files
- Deploy API server
- Install npm dependencies
- Generate configurations
- Start services

### 5. Complete
- Installation summary
- Dashboard URL
- Quick access button

## 🔧 Configuration

### Source Directories

The installer copies files from:
- **Dashboard**: `../status/` → `{install}/dashboard/`
- **API Server**: `../dashcaddy-api/` → `{install}/api/`

### Generated Files

The installer creates:
- `Caddyfile` - Reverse proxy configuration
- `docker-compose.yml` - Container orchestration
- `.dashcaddy-config.json` - Installation settings

### Default Ports

- **Dashboard**: 8080
- **API Server**: 3001
- **Caddy Admin**: 2019

## 🐛 Troubleshooting

### Build Issues
- Ensure Node.js 18+ is installed
- Delete `node_modules` and run `npm install`
- Check that source directories exist

### Runtime Issues
- Run with `npm run dev` to see console errors
- Check that Docker daemon is running
- Verify Caddy is installed and accessible
- Ensure ports 8080, 3001, 2021 are available

### Deployment Issues
- Verify source paths in `file-deployer.js`
- Check write permissions on installation directory
- Ensure sufficient disk space

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📝 License

MIT

## 🙏 Acknowledgments

Built with:
- [Electron](https://www.electronjs.org/) - Cross-platform desktop apps
- [electron-builder](https://www.electron.build/) - Build and packaging
- [Jest](https://jestjs.io/) - Testing framework
- [fast-check](https://fast-check.dev/) - Property-based testing