backsplash-app/PUBLISHING.md

An AI powered wallpaper app.

# Publishing Backsplash Updates to S3

This document describes how to publish app updates to S3 for the auto-update system.

## Prerequisites

1. AWS account with appropriate permissions to write to S3
2. S3 bucket configured for public web hosting
3. AWS credentials (access key and secret key)

## Setting Up Your Environment

1. Create an `.env.production` file in the menubar-app root directory with:

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

Replace `your-backsplash-updates-bucket` with your actual S3 bucket name.

2. **IMPORTANT**: 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

# For Windows PowerShell
$env:AWS_ACCESS_KEY_ID = "your_access_key_id"
$env:AWS_SECRET_ACCESS_KEY = "your_secret_access_key"

# For Windows CMD
set AWS_ACCESS_KEY_ID=your_access_key_id
set AWS_SECRET_ACCESS_KEY=your_secret_access_key
```

## Publishing a New Release

1. Update the version number in `package.json` (must be incremented for update detection)
2. Run `yarn make` to build the app for all platforms
3. Set your AWS credentials as environment variables (see above)
4. Run `yarn publish-s3` to upload the artifacts to S3

The `publish-s3` script is configured to use the `@electron-forge/publisher-s3` publisher with the environment variables set in `.env.production`.

## S3 Bucket Structure

The auto-updater expects a specific structure in your S3 bucket, which is automatically created by the publisher:

```
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
```

The folder structure is configured in `forge.config.ts` to automatically sort files by platform, which is required for the auto-updater to work correctly.

## S3 Bucket Configuration

1. Make sure your S3 bucket has public read permissions
2. Enable static website hosting on the bucket
3. Set appropriate CORS configuration to allow your app to download updates

Example CORS configuration:

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

## Troubleshooting

If updates aren't working:

1. Check S3 bucket permissions (files should be publicly readable)
2. Verify the URL structure in the auto-updater configuration
3. Look at the app logs for any error messages (use the developer tools Console or check the log files)
4. Make sure the version in `package.json` is incremented for each release
5. Verify that the S3 structure matches what the auto-updater expects
6. Test downloading the update artifacts directly from a browser to confirm they are accessible