Ente Cloudron App

This repository contains the Cloudron packaging for Ente, 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
• Serves Ente's bundled web apps from one Cloudron origin using paths
• Keeps generated runtime config and rewritten web assets in /run/ente

Installing

Option 1: Install via Custom App URL (Recommended)

Install directly from the published version catalog — no build required:

1. Go to your Cloudron dashboard
2. Navigate to App Store → Custom App
3. Enter the versions URL:

   https://git.due.ren/andreas/ente-cloudron/-/raw/main/CloudronVersions.json
   

4. Select the latest version and click Install

Updates are published automatically when upstream changes are detected and will appear in your Cloudron dashboard.

Option 2: Build and Install Manually

1. Clone this repository:

   git clone https://git.due.ren/andreas/ente-cloudron.git
   cd ente-cloudron
   

2. Download the Cloudron CLI:

   npm install -g cloudron
   

3. Build the app:

   export BUILD_SERVICE_TOKEN="<build-service-token>"
   export PACKAGE_VERSION="$(jq -r .version CloudronManifest.json)"
   
   cloudron build \
     --build-service-url https://builder.docker.due.ren \
     --build-service-token "$BUILD_SERVICE_TOKEN" \
     build \
     --build-arg "ENTE_GIT_REF=$(cat .upstream-commit)" \
     --repository andreasdueren/ente-cloudron \
     --tag "$PACKAGE_VERSION"
   

4. Install the app:

   cloudron install --location ente.example.com --image "andreasdueren/ente-cloudron:$PACKAGE_VERSION"
   

Configuration

The app is configured automatically using Cloudron's environment variables for:

• PostgreSQL database connection
• SMTP mail service
• App origin URL

SMTP can be overridden when the Cloudron mail relay is unreachable from the app container. Set these app environment variables and restart Ente:

• ENTE_SMTP_HOST
• ENTE_SMTP_PORT
• ENTE_SMTP_USERNAME
• ENTE_SMTP_PASSWORD
• ENTE_SMTP_EMAIL
• ENTE_SMTP_SENDER_NAME
• ENTE_SMTP_ENCRYPTION

Museum supports implicit TLS with ENTE_SMTP_ENCRYPTION=tls or ssl, or no encryption with an empty value. It does not implement SMTP STARTTLS; for external relays use port 465 with tls, or use Cloudron's internal plain SMTP port with an empty encryption value.

For existing installs before these environment overrides are available, append the equivalent settings to /app/data/config/museum.override.yaml:

smtp:
  host: "smtp.example.com"
  port: "465"
  username: "smtp-user"
  password: "smtp-password"
  email: "ente@example.com"
  sender-name: "Ente"
  encryption: "tls"

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 runtime config at /run/ente/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 origin you serve from Cloudron (for example https://ente.example.com) 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:

     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 <bucket> allPrivate --cors-rules "$(<cors.json)"
     

     Adjust the hostname and bucket type as needed; afterwards verify with curl -I -H 'Origin: https://ente.example.com' '<signed-url>' and ensure Access-Control-Allow-Origin is present.
2. During installation, choose only the primary Cloudron app location. The package serves the auxiliary Ente web apps from paths on the same origin:
   • photos: https://ente.<your-domain>/
   • accounts: https://ente.<your-domain>/accounts
   • auth: https://ente.<your-domain>/auth
   • cast: https://ente.<your-domain>/cast
   • albums: https://ente.<your-domain>/albums
   • family: https://ente.<your-domain>/family
   • share: https://ente.<your-domain>/share
   • embed: https://ente.<your-domain>/embed
   • payments: https://ente.<your-domain>/payments
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 runtime config on every start, so you only need to declare the keys you want to override.

   # /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):

   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 </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 lives on the primary hostname you selected during installation, and the auxiliary apps live under path prefixes on that same hostname.

Object storage quick reference

The upstream documentation at 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 or Google Play
2. During login, choose "Custom Server"
3. Enter your Cloudron app URL (e.g., https://ente.yourdomain.com)

Updating

If installed via the Custom App URL, updates appear automatically in your Cloudron dashboard when a new version is published. The CI/CD pipeline checks for upstream Ente changes every 6 hours.

During development, prefer uninstalling and installing a fresh app instance instead of updating an existing one.

License

This Cloudron package is licensed under the same license as Ente (Apache 2.0).