Add comprehensive API documentation to Cloudron setup instructions

- Added detailed API endpoint information in SETUP-INSTRUCTIONS.md - Documented API usage with Ente CLI - Enhanced routing configuration for auth/cast/accounts apps - Updated to version 0.1.64
2025-07-25 11:02:06 -06:00
parent da50bf4773
commit b7fcf5c01d
13 changed files with 876 additions and 58 deletions
--- a/BUILD-INSTRUCTIONS.md
+++ b/BUILD-INSTRUCTIONS.md
@@ -0,0 +1,110 @@
+# 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).