ente-cloudron/BUILD-INSTRUCTIONS.md

Ente Cloudron App Build and Installation Instructions

This document provides detailed instructions for building and installing the Ente Cloudron app, an open-source, end-to-end encrypted photo storage and authentication solution.

Prerequisites

• Cloudron CLI: Ensure the Cloudron CLI is installed and configured on your system. Refer to Cloudron CLI Documentation for setup instructions.
• Docker: Required for local testing or custom builds if needed.
• Git: To clone or manage the repository.
• Repository Access: Ensure you have access to the Ente Cloudron repository at andreasdueren/ente-cloudron.
• Build Service Token: A token for the Cloudron build service is required (provided in the command below).

Build Commands

1. Clone the Repository (if not already done):

   git clone https://github.com/andreasdueren/ente-cloudron.git
   cd ente-cloudron
   

2. Build the App Using Cloudron Build Service: Use the provided build service and token to build the app. Replace <version> with the desired version tag (e.g., 0.1.0 or as per CloudronManifest.json).

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

   Note: The build process should complete within a reasonable time. Monitor the output for any errors.

Installation Commands

1. Install the App on Cloudron: After a successful build, install the app on your Cloudron instance at the desired location (e.g., ente.due.ren).

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

   Important: Do not wait more than 30 seconds for feedback after running the install command. If there's an error, the process may hang, and you should terminate it to troubleshoot. Note: Always uninstall and reinstall during development rather than updating an existing app to ensure a clean setup.

Testing Procedures

1. Verify Installation:

   • Access the app at https://ente.due.ren (or your configured domain).
   • Ensure the Ente web interfaces (Photos, Accounts, Auth, Cast) load correctly.

2. Check S3 Configuration:

   • Confirm that S3 environment variables are set in Cloudron app settings under the 'Environment Variables' section.
   • Variables to check: APP_S3_ENABLED, APP_S3_ENDPOINT, APP_S3_ACCESS_KEY_ID, APP_S3_SECRET_ACCESS_KEY, APP_S3_BUCKET.

3. Monitor Logs for Errors:

   • Use the Cloudron CLI to view logs:

     cloudron logs --app ente.due.ren -f
     

   • Alternatively, shell into the app for detailed log inspection:

     cloudron exec --app ente.due.ren
     tail -f /app/data/logs/*
     

   • Look for S3 connection errors or other issues.

Deployment Steps

1. Post-Installation Configuration:

   • If S3 is not working, update the environment variables in Cloudron app settings and restart the app:

     cloudron restart --app ente.due.ren
     

2. User Authentication:

   • Ente uses its own authentication system. Ensure user registration and login work as expected.
   • If OIDC integration is desired in the future, it can be configured using Cloudron's OIDC variables (CLOUDRON_OIDC_IDENTIFIER, CLOUDRON_OIDC_CLIENT_ID, CLOUDRON_OIDC_CLIENT_SECRET).

Troubleshooting Common Issues

• S3 Configuration Errors:

  • Symptom: App falls back to local storage or logs show S3 connection failures.
  • Solution: Verify S3 environment variables in Cloudron settings. Test connectivity manually using AWS CLI (aws s3 ls s3://<bucket> --endpoint-url <endpoint>).

• Build Failures:

  • Symptom: Build command errors out or hangs.
  • Solution: Check network connectivity to the build service, ensure the token is correct, and review build logs for specific errors.

• Installation Hangs:

  • Symptom: Install command does not complete within 30 seconds.
  • Solution: Terminate the command and check Cloudron logs for errors (cloudron logs --app ente.due.ren). Reinstall if necessary.

• App Not Starting:

  • Symptom: App shows as 'Stopped' or inaccessible after install.
  • Solution: Check logs for startup errors (cloudron logs --app ente.due.ren). Ensure database connectivity and correct configuration.

Configuration Examples

• S3 Environment Variables in Cloudron settings:

  APP_S3_ENABLED=true
  APP_S3_ENDPOINT=s3.amazonaws.com
  APP_S3_ACCESS_KEY_ID=your_access_key
  APP_S3_SECRET_ACCESS_KEY=your_secret_key
  APP_S3_BUCKET=your_bucket_name
  

Additional Resources

• Cloudron Documentation:
  • CLI
  • Packaging Tutorial
  • Manifest Reference
  • Addons Guide
  • Cheat Sheet

For further assistance, contact the Ente team at contact@ente.io or refer to the GitHub repository at https://github.com/ente-io/ente.