Sami
f61e85d9a7
Full codebase including API server (32 modules + routes), dashboard frontend, DashCA certificate distribution, installer script, and deployment skills.
261 lines
6.3 KiB
Markdown
261 lines
6.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 (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
|