ente-cloudron/BUILD-INSTRUCTIONS.md

# Ente Cloudron App Build and Installation Instructions

This document provides detailed instructions for building and installing the Ente Cloudron app, an open-source, end-to-end encrypted photo storage and authentication solution.

## Prerequisites

- **Cloudron CLI**: Ensure the Cloudron CLI is installed and configured on your system. Refer to [Cloudron CLI Documentation](https://docs.cloudron.io/packaging/cli/) for setup instructions.
- **Docker**: Required for local testing or custom builds if needed.
- **Git**: To clone or manage the repository.
- **Repository Access**: Ensure you have access to the Ente Cloudron repository at `andreasdueren/ente-cloudron`.
- **Build Service Token**: A token for the Cloudron build service is required (provided in the command below).

## Build Commands

1. **Clone the Repository** (if not already done):
   ```bash
   git clone https://github.com/andreasdueren/ente-cloudron.git
   cd ente-cloudron
   ```

2. **Build the App Using Cloudron Build Service**:
   Use the provided build service and token to build the app. Replace `<version>` with the desired version tag (e.g., `0.1.0` or as per `CloudronManifest.json`).
   ```bash
   cloudron build --set-build-service builder.docker.due.ren --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e --set-repository andreasdueren/ente-cloudron --tag 1.0.1
   ```
   **Note**: The build process should complete within a reasonable time. Monitor the output for any errors.

## Installation Commands

1. **Install the App on Cloudron**:
   After a successful build, install the app on your Cloudron instance at the desired location (e.g., `ente.due.ren`).
   ```bash
   cloudron install --location ente.due.ren --image andreasdueren/ente-cloudron:1.0.1
   ```
   **Important**: Do not wait more than 30 seconds for feedback after running the install command. If there's an error, the process may hang, and you should terminate it to troubleshoot.
   **Note**: Always uninstall and reinstall during development rather than updating an existing app to ensure a clean setup.

## Testing Procedures

1. **Verify Installation**:
   - Access the app at `https://ente.due.ren` (or your configured domain).
   - Ensure the Ente web interfaces (Photos, Accounts, Auth, Cast) load correctly.

2. **Check S3 Configuration**:
   - Confirm that S3 environment variables are set in Cloudron app settings under the 'Environment Variables' section.
   - Variables to check: `APP_S3_ENABLED`, `APP_S3_ENDPOINT`, `APP_S3_ACCESS_KEY_ID`, `APP_S3_SECRET_ACCESS_KEY`, `APP_S3_BUCKET`.

3. **Monitor Logs for Errors**:
   - Use the Cloudron CLI to view logs:
     ```bash
     cloudron logs --app ente.due.ren -f
     ```
   - Alternatively, shell into the app for detailed log inspection:
     ```bash
     cloudron exec --app ente.due.ren
     tail -f /app/data/logs/*
     ```
   - Look for S3 connection errors or other issues.

## Deployment Steps

1. **Post-Installation Configuration**:
   - If S3 is not working, update the environment variables in Cloudron app settings and restart the app:
     ```bash
     cloudron restart --app ente.due.ren
     ```

2. **User Authentication**:
   - Ente uses its own authentication system. Ensure user registration and login work as expected.
   - If OIDC integration is desired in the future, it can be configured using Cloudron's OIDC variables (`CLOUDRON_OIDC_IDENTIFIER`, `CLOUDRON_OIDC_CLIENT_ID`, `CLOUDRON_OIDC_CLIENT_SECRET`).

## Troubleshooting Common Issues

- **S3 Configuration Errors**:
  - **Symptom**: App falls back to local storage or logs show S3 connection failures.
  - **Solution**: Verify S3 environment variables in Cloudron settings. Test connectivity manually using AWS CLI (`aws s3 ls s3://<bucket> --endpoint-url <endpoint>`).

- **Build Failures**:
  - **Symptom**: Build command errors out or hangs.
  - **Solution**: Check network connectivity to the build service, ensure the token is correct, and review build logs for specific errors.

- **Installation Hangs**:
  - **Symptom**: Install command does not complete within 30 seconds.
  - **Solution**: Terminate the command and check Cloudron logs for errors (`cloudron logs --app ente.due.ren`). Reinstall if necessary.

- **App Not Starting**:
  - **Symptom**: App shows as 'Stopped' or inaccessible after install.
  - **Solution**: Check logs for startup errors (`cloudron logs --app ente.due.ren`). Ensure database connectivity and correct configuration.

## Configuration Examples

- **S3 Environment Variables** in Cloudron settings:
  ```
  APP_S3_ENABLED=true
  APP_S3_ENDPOINT=s3.amazonaws.com
  APP_S3_ACCESS_KEY_ID=your_access_key
  APP_S3_SECRET_ACCESS_KEY=your_secret_key
  APP_S3_BUCKET=your_bucket_name
  ```

## Additional Resources

- **Cloudron Documentation**:
  - [CLI](https://docs.cloudron.io/packaging/cli/)
  - [Packaging Tutorial](https://docs.cloudron.io/packaging/tutorial/)
  - [Manifest Reference](https://docs.cloudron.io/packaging/manifest/)
  - [Addons Guide](https://docs.cloudron.io/packaging/addons/)
  - [Cheat Sheet](https://docs.cloudron.io/packaging/cheat-sheet/)

For further assistance, contact the Ente team at `contact@ente.io` or refer to the GitHub repository at [https://github.com/ente-io/ente](https://github.com/ente-io/ente).