andreas/ente-cloudron
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix Ente Cloudron packaging issues

Browse Source 
- Fixed admin-helper.sh to use correct Museum binary path (/app/museum-bin/museum)
- Updated start.sh to handle missing S3 configuration gracefully
  - App now starts in configuration mode when S3 is not configured
  - Shows helpful configuration page instead of failing health checks
  - Properly starts Museum server once S3 is configured
- Updated CloudronManifest.json to version 0.2.2
- All web frontends (photos, accounts, auth, cast, albums, family) verified working
- Museum API server running successfully with S3 storage

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Your Name
2025-10-21 19:20:15 -06:00
parent 61046f1d42
commit 37cd205a07
6 changed files with 686 additions and 1298 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
BUILD-INSTRUCTIONS.md
View File

@@ -1,110 +1,66 @@
# 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.
# Ente Cloudron App – Build & Deployment Guide
## Prerequisites
- Cloudron CLI (`npm install -g cloudron`) configured for your server
- Docker (for local test builds, optional when using the Cloudron build service)
- Access to this repository (`andreasdueren/ente-cloudron`)
- Cloudron build-service token: `e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e`
- **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):
## Build
1. Clone the repository (if needed):
```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`).
2. Build the image via the Cloudron build service. Adjust `--tag` to match `CloudronManifest.json` (`0.2.1`) and optionally override the Ente git ref:
```bash
cloudron build --set-build-service builder.docker.due.ren --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e --set-repository andreasdueren/ente-cloudron --tag 1.0.1
cloudron build \
--set-build-service builder.docker.due.ren \
--build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e \
--set-repository andreasdueren/ente-cloudron \
--tag 0.2.1 \
--build-arg ENTE_GIT_REF=main
```
**Note**: The build process should complete within a reasonable time. Monitor the output for any errors.
Use a tagged Ente release for reproducible builds (e.g. `--build-arg ENTE_GIT_REF=v0.9.0`).
## Installation Commands
## Install / Reinstall
Always uninstall the dev instance before reinstalling.
```bash
cloudron install \
--location ente.due.ren \
--image andreasdueren/ente-cloudron:0.2.1
```
If the install command runs for more than ~30 seconds without feedback, abort and inspect `cloudron logs --app ente.due.ren`.
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`).
## Smoke Tests
1. Open `https://ente.due.ren/health` and ensure it returns `status: OK`.
2. Navigate to `/photos`, `/accounts`, `/auth`, `/cast`, `/albums`, `/family` to confirm static assets load.
3. Tail logs while signing up a user to verify Museum output:
```bash
cloudron install --location ente.due.ren --image andreasdueren/ente-cloudron:1.0.1
cloudron logs --app ente.due.ren -f
```
**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
## Required Configuration
Populate `/app/data/config/s3.env` with valid S3 credentials and restart the app.
```bash
S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com
S3_REGION=auto
S3_BUCKET=ente-due-ren
S3_ACCESS_KEY=XXXXXXXX
S3_SECRET_KEY=YYYYYYYY
S3_PREFIX=optional/path
```
Optional: set `CLOUDRON_OIDC_IDENTIFIER`, `CLOUDRON_OIDC_CLIENT_ID`, and `CLOUDRON_OIDC_CLIENT_SECRET` in the Cloudron UI to enable SSO in the generated Museum configuration.
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.
## Troubleshooting
- **S3 errors**: Verify credentials in `/app/data/config/s3.env`; check connectivity using `aws s3 ls --endpoint-url ...` from a trusted host.
- **Museum not starting**: Inspect `/app/data/museum/configurations/local.yaml` for syntax issues; delete to regenerate.
- **Frontend stale after update**: Restart the app—the startup script re-syncs static assets on each boot.
- **OIDC issues**: Confirm the callback URL `/api/v1/session/callback` is allowed in the Cloudron SSO client configuration.
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).
## Useful Commands
```bash
cloudron exec --app ente.due.ren -- cat /app/data/museum/configurations/local.yaml
cloudron exec --app ente.due.ren -- ente --help
cloudron logs --app ente.due.ren -f
```