backsplash-app/BUILDING.md

An AI powered wallpaper app.

# Building and Releasing Backsplash

This document outlines the process for building and releasing Backsplash across different platforms.

## Overview

Backsplash uses GitHub Actions for automated builds and releases. The build process:
1. Builds the app for Windows, macOS, and Linux
2. Signs the builds with appropriate certificates
3. Notarizes macOS builds
4. Publishes to S3 for auto-updates
5. Creates a GitHub Release with all builds

## Prerequisites

### Required Accounts and Credentials

1. **Apple Developer Account**
   - Apple Developer ID certificate
   - App-Specific Password for notarization
   - Team ID

2. **Windows Code Signing Certificate**
   - Code signing certificate (.pfx file)
   - Certificate password

3. **AWS Account**
   - S3 bucket for auto-updates
   - AWS access key and secret key

### GitHub Secrets

Add these secrets to your GitHub repository (Settings > Secrets and Variables > Actions):

```
# AWS S3 Configuration
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
S3_BUCKET
S3_REGION

# Apple Notarization
APPLE_ID
APPLE_ID_PASSWORD
APPLE_TEAM_ID
APPLE_DEVELOPER_IDENTITY
MACOS_CERTIFICATE (base64 encoded .p12 file)
MACOS_CERTIFICATE_PASSWORD
MACOS_KEYCHAIN_PASSWORD

# Windows Code Signing
WINDOWS_CERTIFICATE (base64 encoded .pfx file)
WINDOWS_CERTIFICATE_PASSWORD
```

## Building Locally

### Development Build

```bash
# Install dependencies
yarn install

# Start development server
yarn dev
```

### Production Build

```bash
# Build for current platform
yarn make

# Build for specific platform
yarn make -- --platform=darwin  # macOS
yarn make -- --platform=win32   # Windows
yarn make -- --platform=linux   # Linux
```

## Automated Builds

The build process is automated using GitHub Actions. The workflow is triggered by:
1. Pushing a new version tag (e.g., `v1.0.0`)
2. Manual workflow dispatch

### Build Process

1. **Setup**
   - Checkout code
   - Setup Node.js
   - Install dependencies
   - Configure environment variables

2. **Platform-Specific Steps**
   - **macOS**
     - Setup certificates
     - Build DMG and ZIP
     - Notarize builds
   - **Windows**
     - Setup certificates
     - Build EXE installer
   - **Linux**
     - Build AppImage and DEB packages

3. **Publishing**
   - Upload builds to S3 for auto-updates
   - Create GitHub Release with all builds

## Release Process

1. **Version Update**
   ```bash
   # Update version in package.json
   # Commit changes
   git add package.json
   git commit -m "Bump version to x.y.z"
   ```

2. **Create and Push Tag**
   ```bash
   git tag vx.y.z
   git push origin vx.y.z
   ```

3. **Monitor Build**
   - Check GitHub Actions tab for build progress
   - Verify all platforms build successfully
   - Check S3 uploads
   - Verify GitHub Release creation

## Troubleshooting

### Common Issues

1. **Build Failures**
   - Check GitHub Actions logs
   - Verify all secrets are correctly set
   - Ensure certificates are valid and not expired

2. **Notarization Issues**
   - Verify Apple ID credentials
   - Check notarization logs in Apple Developer portal
   - Ensure hardened runtime is enabled

3. **Code Signing Issues**
   - Verify certificates are correctly installed
   - Check certificate expiration dates
   - Ensure correct certificate passwords

### Getting Help

If you encounter issues:
1. Check the GitHub Actions logs
2. Review the Electron Forge documentation
3. Check platform-specific signing requirements
4. Contact the development team

## Platform-Specific Notes

### macOS
- Requires Apple Developer ID certificate
- Builds are notarized for distribution
- Supports DMG and ZIP formats

### Windows
- Requires code signing certificate
- Uses Squirrel for auto-updates
- Supports EXE installer

### Linux
- No code signing required
- Supports AppImage and DEB formats
- Can be built on any platform

## Maintenance

### Certificate Renewal

1. **Apple Developer Certificate**
   - Renew through Apple Developer portal
   - Update `MACOS_CERTIFICATE` secret
   - Test build and notarization

2. **Windows Certificate**
   - Renew through certificate provider
   - Update `WINDOWS_CERTIFICATE` secret
   - Test build and signing

### AWS Credentials

- Rotate AWS credentials periodically
- Update GitHub secrets when credentials change
- Test S3 uploads after credential updates