Initial commit: DashCaddy v1.0
Full codebase including API server (32 modules + routes), dashboard frontend, DashCA certificate distribution, installer script, and deployment skills.
This commit is contained in:
260
dashcaddy-installer/BUILD_GUIDE.md
Normal file
260
dashcaddy-installer/BUILD_GUIDE.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user