ente-cloudron/POSTINSTALL.md

Your Ente installation is almost ready!

Required: External Object Storage

Before using Ente, configure an S3-compatible object storage provider:

1. Open the Cloudron dashboard and select your Ente app.
2. Launch the file explorer.
3. Open /app/data/config/s3.env and provide values for all required keys.
4. Save the file and restart the app from the Cloudron dashboard.
5. (Required for cast/slideshow) Configure your S3 bucket’s CORS policy to allow the Ente domains you serve from Cloudron (e.g. https://ente.due.ren, https://accounts.due.ren, https://cast.due.ren, etc.). Without CORS, browsers will block the signed URLs that power the cast slideshow.
   • Backblaze B2 tip: B2 ships with “native” CORS rules that block S3-style updates. Install the Backblaze CLI pip install 'b2<4', then:

     # Authorise once (replace with your key ID/secret)
     b2 authorize-account <KEY_ID> <APP_KEY>
     
     # Inspect the current bucket type (usually allPrivate) and capture it
     BUCKET_TYPE=$(b2 get-bucket ente-due-ren | awk -F'"' '/bucketType/ {print $4}')
     
     # Clear any native rules without changing visibility
     b2 update-bucket ente-due-ren "$BUCKET_TYPE" --cors-rules '[]'
     
     # Apply the S3-compatible rule (adjust origins as needed)
     cat >cors.json <<'EOF'
     [
       {
         "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 "$BUCKET_TYPE" --cors-rules "$(<cors.json)"
     

     Verify with curl -I -H 'Origin: https://ente.due.ren' <signed-url>; you should see Access-Control-Allow-Origin.

Supported variables (these map directly to the fields described in the upstream “Configuring Object Storage” documentation):

• S3_ENDPOINT (e.g. https://<account>.r2.cloudflarestorage.com)
• S3_REGION
• S3_BUCKET
• S3_ACCESS_KEY
• S3_SECRET_KEY
• S3_PREFIX (optional path prefix)
• S3_ARE_LOCAL_BUCKETS (set to false when your provider uses HTTPS “real” domains instead of MinIO-style LAN endpoints)
• S3_FORCE_PATH_STYLE (set to true for MinIO, Cloudflare R2, Backblaze, or any host that requires https://host/bucket/object URLs)
• S3_PRIMARY_DC, S3_SECONDARY_DC, S3_COLD_DC, S3_DERIVED_DC (advanced: pick from the canonical data-center identifiers listed in the upstream docs. The names are hard-coded in Museum; leave them at b2-eu-cen, wasabi-eu-central-2-v3, scw-eu-fr-v3 unless you know you need one of the legacy aliases such as scw-eu-fr.)
• Optional replication: define both S3_SECONDARY_* and S3_COLD_* (endpoints, keys, secrets, optional prefixes, DC names) to mirror uploads to a second hot bucket and a third cold bucket. Replication is only enabled when all three buckets are configured; otherwise the app stays in single-bucket mode. See Ente’s object storage guide for sample layouts and discussion of reliability.

You should never edit the generated /app/data/museum/configurations/local.yaml directly. If you need to append extra settings (for example, defining internal.super-admins), create /app/data/config/museum.override.yaml and add only the keys you want to override. Copying the entire sample s3: block from the docs into that file will erase the credentials that the package renders from s3.env and break replication.

Required: Secondary Hostnames

The installer now asks for dedicated hostnames for the Auth/Accounts/Cast/Albums/Family web apps (via Cloudron httpPorts). If you manage DNS outside of Cloudron, create CNAME/A records such as accounts.<app-domain>, auth.<app-domain>, etc., pointing at the primary app domain. With Cloudron-managed DNS the records are created automatically.

Administration

• Grant yourself admin privileges

  1. Open the Cloudron dashboard → your Ente app → File Manager.
  2. Navigate to /app/data/config/ and open (or create) museum.override.yaml.
  3. Add your email to the super-admin list:

     internal:
       super-admins:
         - you@example.com
     

  4. Save the file and restart the app. The override is appended to Museum’s configuration on every start.

• Sign in to the bundled CLI The package now preconfigures the CLI (config: /app/data/cli-data/config.yaml, exports: /app/data/cli-data/export).
  From the Cloudron Terminal run:

  # authenticate once (enter the OTP you receive by email)
  sudo -u cloudron ente account add
  
  # inspect available commands
  sudo -u cloudron ente --help
  

  After you’re signed in you can follow the upstream docs for tasks like increasing storage: see user administration and the CLI reference. The object storage guide explains the reliability setup: fill out S3_*, S3_SECONDARY_*, and S3_COLD_* in /app/data/config/s3.env, and the package will automatically enable three-bucket replication when you restart (no extra toggle needed).