163 lines
9.1 KiB
Markdown
163 lines
9.1 KiB
Markdown
# Ente Cloudron App
|
||
|
||
This repository contains the Cloudron packaging for [Ente](https://ente.io), an open-source, end-to-end encrypted alternative to Google Photos and Apple Photos.
|
||
|
||
## Features
|
||
|
||
- Self-host your own encrypted photo backup service
|
||
- Automatically integrates with Cloudron's PostgreSQL database
|
||
- Configured to use Cloudron's mail service for sending emails
|
||
- Easy to deploy and manage through the Cloudron interface
|
||
|
||
## Building and Installing
|
||
|
||
### Option 1: Build and Install Manually
|
||
|
||
1. Clone this repository:
|
||
```
|
||
git clone https://github.com/yourusername/ente-cloudron.git
|
||
cd ente-cloudron
|
||
```
|
||
|
||
2. Download the Cloudron CLI:
|
||
```
|
||
npm install -g cloudron
|
||
```
|
||
|
||
3. Build the app:
|
||
```
|
||
cloudron build
|
||
```
|
||
|
||
4. Install the app:
|
||
```
|
||
cloudron install --app ente.yourdomain.com
|
||
```
|
||
|
||
### Option 2: Install from the Cloudron App Store
|
||
|
||
Once this app is accepted into the Cloudron App Store, you can install it directly:
|
||
|
||
1. Go to your Cloudron dashboard
|
||
2. Click "App Store"
|
||
3. Search for "Ente"
|
||
4. Click "Install"
|
||
|
||
## Configuration
|
||
|
||
The app is configured automatically using Cloudron's environment variables for:
|
||
|
||
- PostgreSQL database connection
|
||
- SMTP mail service
|
||
- App origin URL
|
||
|
||
### Cloudron Admin Notes
|
||
|
||
After installing on Cloudron remember to:
|
||
|
||
1. Open the File Manager for the app, edit `/app/data/config/s3.env`, and set the S3-compatible credentials that belong in `museum.yaml`. The upstream documentation expects the canonical keys `b2-eu-cen` (primary), `wasabi-eu-central-2-v3` (secondary) and `scw-eu-fr-v3` (cold); this package renders those blocks automatically from the environment variables below so you don’t have to touch the generated config. At minimum set `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, plus the optional `S3_PREFIX`. To enable replication you must also define **both** `S3_SECONDARY_*` and `S3_COLD_*` (endpoint, region, bucket, key, secret, optional prefix/DC overrides); after a restart the package will flip `replication.enabled` on your behalf when all three buckets are present. Advanced knobs from the documentation map to the following variables:
|
||
- `S3_ARE_LOCAL_BUCKETS=false` toggles SSL/subdomain-style URLs (`are_local_buckets` in `museum.yaml`); leave it at `true` for MinIO-style setups.
|
||
- `S3_FORCE_PATH_STYLE=true` translates to `use_path_style_urls=true` (required for R2/MinIO and most LAN storage).
|
||
- The data-center identifiers (`b2-eu-cen`, `wasabi-eu-central-2-v3`, `scw-eu-fr-v3`, etc.) are **hard-coded upstream**. Keep the defaults unless you know you are targeting one of the legacy names (as listed in the Ente docs). The start script will ignore unknown values to prevent replication from breaking with empty bucket names.
|
||
- Leave the generated `museum/configurations/local.yaml` alone—if you need to append extra settings, do so via `/app/data/config/museum.override.yaml` and only add the keys you actually want to change. Copy‑pasting the full sample `s3:` block from the docs will overwrite the generated credentials with blanks.
|
||
- If you are using Cloudflare R2 or another hosted S3 provider, configure your bucket’s CORS policy to allow the Ente frontends (e.g. `https://ente.due.ren`, `https://accounts.due.ren`, `https://cast.due.ren`, **and** the desktop scheme `ente://app`) so that cast/slideshow playback and the desktop client can fetch signed URLs directly from storage. Backblaze B2 also requires clearing its “native” CORS rules; see the script in `POSTINSTALL.md`. When using the Backblaze CLI remember to preserve your bucket visibility (`allPrivate` for most installs): run `b2 get-bucket <bucket>` to confirm the current type, then invoke `b2 update-bucket <bucket> <bucketType> --cors-rules "$(<cors.json)"` so you only touch the CORS block. A minimal rule that works with Ente’s signed URLs looks like:
|
||
```bash
|
||
cat <<'EOF' >cors.json
|
||
[
|
||
{
|
||
"corsRuleName": "entephotos",
|
||
"allowedOrigins": ["*"],
|
||
"allowedHeaders": ["*"],
|
||
"allowedOperations": [
|
||
"b2_download_file_by_id",
|
||
"b2_download_file_by_name",
|
||
"b2_upload_file",
|
||
"b2_upload_part",
|
||
"s3_get",
|
||
"s3_post",
|
||
"s3_put",
|
||
"s3_head"
|
||
],
|
||
"exposeHeaders": ["X-Amz-Request-Id","X-Amz-Id-2","ETag"],
|
||
"maxAgeSeconds": 3600
|
||
}
|
||
]
|
||
EOF
|
||
b2 update-bucket ente-due-ren allPrivate --cors-rules "$(<cors.json)"
|
||
```
|
||
Adjust the hostnames and bucket type as needed; afterwards verify with `curl -I -H 'Origin: https://cast.example.com' '<signed-url>'` and ensure `Access-Control-Allow-Origin` is present.
|
||
2. When prompted during installation, pick hostnames for the Accounts/Auth/Cast/Albums/Family web apps (they are exposed via Cloudron `httpPorts`). Ensure matching DNS records exist; Cloudron-managed DNS creates them automatically, otherwise point CNAME/A records such as `accounts.<app-domain>` at the primary hostname.
|
||
3. To persist tweaks to Museum (for example, seeding super-admin or whitelist entries), create `/app/data/config/museum.override.yaml`. Its contents are appended to the generated `museum/configurations/local.yaml` on every start, so you only need to declare the keys you want to override.
|
||
```yaml
|
||
# /app/data/config/museum.override.yaml
|
||
internal:
|
||
super-admins:
|
||
- admin@example.com
|
||
```
|
||
4. Use the bundled Ente CLI for admin tasks via `cloudron exec --app <location> -- sudo -u cloudron ente --help`. On a fresh install run the following once (initialises the CLI config, whitelists your admin, and clears the CLI DB):
|
||
```bash
|
||
cloudron exec --app ente.cloudron.io -- bash -lc \
|
||
'cat <<EOF >/cli-data/config.yaml
|
||
endpoint:
|
||
api: https://ente.cloudron.io/api
|
||
log:
|
||
http: false
|
||
EOF
|
||
mkdir -p /cli-data/export
|
||
chown cloudron:cloudron /cli-data /cli-data/config.yaml /cli-data/export
|
||
cat <<EOF >/app/data/config/museum.override.yaml
|
||
internal:
|
||
super-admins:
|
||
- admin@example.com
|
||
EOF
|
||
rm -f /cli-data/ente-cli.db
|
||
chown cloudron:cloudron /app/data/config/museum.override.yaml'
|
||
|
||
cloudron restart --app ente.cloudron.io
|
||
|
||
# add your account (respond to prompts with the OTP sent to your email)
|
||
cloudron exec --app ente.cloudron.io -- sudo -u cloudron ente account add
|
||
```
|
||
Afterwards the usual admin commands work as documented. Example:
|
||
```bash
|
||
cloudron exec --app ente.cloudron.io -- sudo -u cloudron ente admin list-users --admin-user admin@example.com
|
||
```
|
||
|
||
The main photos UI continues to live on the hostname you selected during installation.
|
||
|
||
### Object storage quick reference
|
||
|
||
The upstream documentation at [ente.io/help/self-hosting/administration/object-storage](https://ente.io/help/self-hosting/administration/object-storage) is written for bare-metal installs where you edit `museum.yaml` by hand. The Cloudron package wraps those steps so you only maintain `/app/data/config/s3.env`, but the same concepts apply:
|
||
|
||
- **Canonical bucket names.** Museum’s schema ships with `b2-eu-cen`, `wasabi-eu-central-2-v3`, and `scw-eu-fr-v3`. You can point those identifiers at any S3-compatible provider, but you cannot rename them—replication logic only understands the upstream keys (or their documented legacy aliases). Leave the defaults in `s3.env` and only change the credentials/endpoints under each key.
|
||
- **Three buckets for replication.** Replication only works when two “hot” buckets and one “cold” bucket are configured. Populate `S3_*`, `S3_SECONDARY_*`, and `S3_COLD_*`; once all three have endpoints/keys/secrets the package automatically writes the `replication.enabled: true` stanza.
|
||
- **Transport settings.** Set `S3_ARE_LOCAL_BUCKETS=true`/`false` and `S3_FORCE_PATH_STYLE=true` to mirror the documentation’s `are_local_buckets`/`use_path_style_urls` toggles when talking to MinIO, Cloudflare R2, or other providers that require path-style URLs over HTTPS.
|
||
- **CORS.** If browsers cannot upload/download because of CORS, apply the recommended JSON from the docs (or the Backblaze helper script in `POSTINSTALL.md`). Ensure `Content-MD5` is listed in `AllowedHeaders` for providers with allow-lists.
|
||
- **Do not overwrite the generated config.** Keep `/app/data/config/museum.override.yaml` minimal (only the keys you need). Dropping the example `s3:` block from the docs into that file will clear the generated credentials and replication will fail with “PutObjectInput.Bucket” errors.
|
||
|
||
## Usage
|
||
|
||
### Web Client
|
||
|
||
After installation, you can access the Ente web client at your app's URL. Create the first user and promote them to an administrator using the override file or upstream admin tooling as documented by Ente.
|
||
|
||
### Mobile Apps
|
||
|
||
You can use the official Ente mobile apps with your self-hosted server:
|
||
|
||
1. Download the Ente app from the [App Store](https://apps.apple.com/app/id1542026904) or [Google Play](https://play.google.com/store/apps/details?id=io.ente.photos)
|
||
2. During login, choose "Custom Server"
|
||
3. Enter your Cloudron app URL (e.g., `https://ente.yourdomain.com`)
|
||
|
||
## Updating
|
||
|
||
To update to a newer version:
|
||
|
||
```
|
||
cloudron update --app ente.yourdomain.com
|
||
```
|
||
|
||
## License
|
||
|
||
This Cloudron package is licensed under the same license as Ente (Apache 2.0).
|