affine-cloudron/BUILD.md

AFFiNE Cloudron Package Build Guide

Prerequisites

• Cloudron CLI logged into your Cloudron server (cloudron login)
• Access to the Cloudron build service builder.docker.due.ren
• Docker installed locally (required by the Cloudron build tooling)
• Git repository checked out with this packaging folder
• Cloudron admin credentials to install the resulting app image

Build Commands

cloudron build \
  --set-build-service builder.docker.due.ren \
  --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e \
  --set-repository andreasdueren/ente-cloudron \
  --tag 0.1.0

Deployment Steps

1. Remove any previous dev install of AFFiNE on the Cloudron (always reinstall from scratch).
2. Install the freshly built image:

   cloudron install --location ente.due.ren --image andreasdueren/ente-cloudron:0.1.0
   

3. When prompted, confirm the app info and wait for Cloudron to report success (abort after ~30 seconds if installation stalls or errors to avoid hanging sessions).
4. Visit https://ente.due.ren (or the chosen location) and sign in using Cloudron SSO.

Testing Checklist

• Open the app dashboard and ensure the landing page loads without 502/504 errors.
• Create a workspace, add a note, upload an asset, and reload to confirm /app/data persistence.
• Trigger OIDC login/logout flows to verify Cloudron SSO works (callback /api/v1/session/callback).
• Send an invitation email to validate SMTP credentials wired from the Cloudron mail addon.
• Inspect logs with cloudron logs --app ente.due.ren -f for migration output from scripts/self-host-predeploy.js.

Troubleshooting

• Migrations hang: restart the app; migrations rerun automatically before the server starts. Check PostgreSQL reachability via cloudron exec --app <id> -- env | grep DATABASE_URL.
• Login issues: confirm the Cloudron OIDC client is enabled for the app and that the callback URL /api/v1/session/callback is allowed.
• Email failures: verify the Cloudron sendmail addon is provisioned and that MAILER_* env vars show up inside the container (cloudron exec --app <id> -- env | grep MAILER).
• Large uploads rejected: adjust client_max_body_size in nginx.conf if you routinely exceed 200 MB assets, then rebuild.

Configuration Notes

• Persistent config lives in /app/data/config/config.json. Modify values (e.g., Stripe, throttling) and restart the app; the file is backed up by Cloudron.
• Uploaded files live in /app/data/storage and map to ~/.affine/storage inside the runtime.
• Default health check hits /api/healthz; customize via CloudronManifest.json if upstream changes.