Enable Ente CLI persistence and update docs

2025-10-30 11:17:11 -06:00
parent f62914d566
commit 18d14d09df
6 changed files with 64 additions and 62 deletions
--- a/BUILD-INSTRUCTIONS.md
+++ b/BUILD-INSTRUCTIONS.md
@@ -1,68 +1,34 @@
-# 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`
+# Ente Cloudron – Quick Guide

 ## Build
-1. Clone the repository (if needed):
-   ```bash
-   git clone https://github.com/andreasdueren/ente-cloudron.git
-   cd ente-cloudron
-   ```
-2. Build the image via the Cloudron build service. Adjust `--tag` to match `CloudronManifest.json` (`0.4.3`) 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 0.4.3 \
-     --build-arg ENTE_GIT_REF=main
-   ```
-   Use a tagged Ente release for reproducible builds (e.g. `--build-arg ENTE_GIT_REF=v0.9.0`).
+```bash
+git clone https://github.com/andreasdueren/ente-cloudron.git
+cd ente-cloudron

-## Install / Reinstall
-Always uninstall the dev instance before reinstalling.
+cloudron build \
+  --set-build-service builder.docker.due.ren \
+  --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e \
+  --set-repository andreasdueren/ente-cloudron \
+  --tag 0.4.5
+```
+
+## Install
 ```bash
 cloudron install \
  --location ente.due.ren \
-  --image andreasdueren/ente-cloudron:0.4.3
+  --image andreasdueren/ente-cloudron:0.4.5
 ```
-If the install command runs for more than ~30 seconds without feedback, abort and inspect `cloudron logs --app 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 logs --app ente.due.ren -f
-   ```
+## After Install
+1. **S3** – In Cloudron File Manager open `/app/data/config/s3.env`, fill in your endpoint/region/bucket/access/secret, then restart the app from the dashboard.
+2. **Subdomains** – In the app’s *Domains* tab add aliases for `accounts`, `auth`, `cast`, `albums`, `family`. Create matching DNS records pointing at the primary domain (e.g. if the app is `ente.due.ren`, add `accounts.due.ren → ente.due.ren`, etc.).

-## 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.
+Once DNS propagates, use the dedicated hosts:
+- `https://<app-host>` (the hostname you chose during install, main UI & uploads)
+- `https://accounts.<domain>`
+- `https://auth.<domain>`
+- `https://cast.<domain>`
+- `https://albums.<domain>`
+- `https://family.<domain>`

-## Troubleshooting
- **S3 errors**: Verify credentials in `/app/data/config/s3.env`; check connectivity using `aws s3 ls --endpoint-url ...` from a trusted host.
- **Startup issues**: Inspect `/app/data/logs/startup.log` (also mirrored to `cloudron logs`) for rendered configuration and error messages.
- **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.
-
-## 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
-cloudron exec --app ente.due.ren -- tail -f /app/data/logs/startup.log
-```
+Check `cloudron logs --app ente.due.ren -f` or `/app/data/logs/startup.log` if anything looks off.
--- a/CloudronManifest.json
+++ b/CloudronManifest.json
@@ -7,12 +7,13 @@
  "contactEmail": "contact@ente.io",
  "website": "https://ente.io",
  "tagline": "Open source, end-to-end encrypted photo backup",
-  "version": "0.4.3",
+  "version": "0.4.5",
  "upstreamVersion": "git-main",
  "healthCheckPath": "/health",
  "httpPort": 3080,
  "memoryLimit": 1610612736,
  "postInstallMessage": "file://POSTINSTALL.md",
+  "multiDomain": true,
  "addons": {
    "localstorage": {},
    "postgresql": {},
@@ -24,6 +25,9 @@
  "checklist": {
    "configure-object-storage": {
      "message": "Configure your S3-compatible storage in /app/data/config/s3.env before first use."
+    },
+    "configure-subdomains": {
+      "message": "Create DNS records and add Cloudron aliases for accounts., auth., cast., albums. and family. (using the base domain of this app)."
    }
  },
  "icon": "file://logo.png",
--- a/3
+++ b/3
@@ -105,6 +105,9 @@ COPY admin-helper.sh /app/pkg/admin-helper.sh
 COPY admin-helper-direct.sh /app/pkg/admin-helper-direct.sh

 RUN chmod +x /app/pkg/start.sh /app/pkg/admin-helper.sh /app/pkg/admin-helper-direct.sh
+RUN ln -s /app/data/cli-data /cli-data && \
+    rm -rf /home/cloudron && \
+    ln -s /app/data/home /home/cloudron

 EXPOSE 3080 8080

--- a/POSTINSTALL.md
+++ b/POSTINSTALL.md
@@ -20,11 +20,29 @@ Supported variables:
 - `S3_SECRET_KEY`
 - `S3_PREFIX` (optional path prefix)

+## Required: DNS Subdomains
+
+Ente now serves supporting apps on dedicated hosts. Create DNS records (CNAME or A) for:
+
+- `accounts.<root-domain>`
+- `auth.<root-domain>`
+- `cast.<root-domain>`
+- `albums.<root-domain>`
+- `family.<root-domain>`
+
+For example, if you installed the app at `ente.due.ren`, create records for `accounts.due.ren`, `auth.due.ren`, etc., all pointing to `ente.due.ren`. After adding the DNS records, open the Cloudron dashboard → Ente app → Domains tab and add each hostname as an alias. DNS propagation must complete before the `/accounts` and `/auth` apps will accept sessions.
+
 ## Next Steps

 - Visit the app URL and create the first administrator account.
 - Configure the Ente mobile apps to use your custom server (`Settings → Advanced → Custom Server`).
 - Optional: set the environment variables `CLOUDRON_OIDC_IDENTIFIER`, `CLOUDRON_OIDC_CLIENT_ID`, and `CLOUDRON_OIDC_CLIENT_SECRET` to enable Cloudron SSO in the generated Museum config.
+- Administrative CLI tooling is available inside the container. Open a terminal and run:
+  ```bash
+  cloudron exec --app ente.due.ren -- sudo -u cloudron ente --help
+  cloudron exec --app ente.due.ren -- sudo -u cloudron ente admin --help
+  ```
+  The CLI stores its state at `/app/data/cli-data` (inside the container it is available at `/cli-data`). Consult the upstream CLI guide for per-command usage, including storage quota adjustments.

 ## Administration Helpers

--- a/README.md
+++ b/README.md
@@ -81,9 +81,15 @@ The package includes several enhancements to ensure proper functionality:
 2. **API Configuration**: Dynamic runtime configuration to ensure the frontend connects to the correct API endpoint
 3. **CORS Headers**: Proper CORS configuration for API access

-You need to manually set up and configure:
+### Cloudron Admin Notes

- S3-compatible object storage
+After installing on Cloudron remember to:
+
+1. Open the File Manager for the app, edit `/app/data/config/s3.env` with your object storage endpoint/keys, and restart the app.
+2. Add alias domains for `accounts`, `auth`, `cast`, `albums`, and `family` in the app’s **Domains** tab (create matching DNS records pointing to the primary hostname).
+3. Use the bundled Ente CLI for admin tasks via `cloudron exec --app <location> -- sudo -u cloudron ente --help`. The CLI stores its state in `/app/data/cli-data` (exposed inside the container at `/cli-data`) and already trusts your app’s API endpoint.
+
+The main photos UI continues to live on the hostname you selected during installation.

 ## Usage

@@ -121,4 +127,4 @@ For issues with Ente itself, please refer to the [main Ente repository](https://

 ## License

-This Cloudron package is licensed under the same license as Ente (Apache 2.0). 
+This Cloudron package is licensed under the same license as Ente (Apache 2.0). 
--- a/start.sh
+++ b/start.sh
@@ -518,6 +518,11 @@ if [ -d "$WEB_RUNTIME_DIR" ]; then
 fi

 log INFO "Ensuring CLI configuration"
+CLI_DATA_DIR="$DATA_DIR/cli-data"
+mkdir -p "$CLI_DATA_DIR"
+chown cloudron:cloudron "$CLI_DATA_DIR"
+chmod 700 "$CLI_DATA_DIR"
+
 CLI_HOME="$DATA_DIR/home/.ente"
 mkdir -p "$CLI_HOME"
 cat > "$CLI_HOME/config.yaml" <<EOF_CLI