backsplash-app/AUTO-UPDATES.md

An AI powered wallpaper app.

# Auto-Update System Setup

This document provides a quick guide on configuring and using Backsplash's auto-update system.

## Overview

Backsplash uses Electron Forge with S3 publishing for automatic updates. The system:

1. Publishes builds to an S3 bucket
2. Checks for updates when the app starts and periodically afterward
3. Notifies users when updates are available
4. Downloads and installs updates with user permission

## Setting Up S3

1. **Create an S3 bucket** with public read access
2. **Enable static website hosting** on the bucket
3. Add **CORS configuration** to allow downloads:

```json
[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3000
  }
]
```

## Configuration

1. Create `.env.production` file in the project root:

```
# S3 Auto-update Configuration
S3_BUCKET=your-backsplash-updates-bucket
S3_REGION=us-east-1
S3_FOLDER=backsplash-releases/
```

2. **Never commit AWS credentials** to the repository. Set them as environment variables before publishing:

```bash
# For macOS/Linux
export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key
```

## Publishing Updates

1. Update the version in `package.json` - this is critical as the version number is used to determine if an update is available
2. Build the app: `yarn make`
3. Set AWS credentials as environment variables
4. Publish: `yarn publish-s3`

## Expected S3 Structure

The publisher automatically creates the following structure:

```
s3://your-backsplash-updates-bucket/backsplash-releases/
└── win/
    ├── RELEASES
    ├── backsplash-app-1.1.0-full.nupkg
    └── backsplash-app-setup-1.1.0.exe
└── mac/
    └── backsplash-app-1.1.0-mac.zip
└── linux/
    └── backsplash-app-1.1.0.AppImage
```

This structure is automatically created by the S3 publisher configuration in `forge.config.ts`, which sorts files by platform.

## Update Mechanism

1. App checks for updates on startup and every 4 hours
2. When updates are found, a notification appears in the app interface
3. User can download and install the update
4. Application restarts with the new version

## Troubleshooting

- Check S3 bucket permissions (files must be publicly readable)
- Verify correct version increment in `package.json`
- Examine app logs for error messages (`electron-log` is used for logging)
- Ensure AWS credentials are correctly set
- Verify S3 folder structure matches expected format

For detailed information on the publishing process, see [PUBLISHING.md](./PUBLISHING.md).