Add auto-update feature for pgAdmin 4 desktop (macOS only). #5766

Author: anilsahoo20

Makefile

@@ -20,8 +20,9 @@ APP_REVISION := $(shell grep ^APP_REVISION web/version.py | awk -F"=" '{print $$
 # Include only platform-independent builds in all
 all: docs pip src
 
+# Add BUILD_OPTS variable to pass arguments
 appbundle:
-	./pkg/mac/build.sh
+	./pkg/mac/build.sh $(BUILD_OPTS)
 
 install-node:
 	cd web && yarn install

docs/en_US/desktop_deployment.rst

@@ -128,3 +128,140 @@ The configuration settings are stored in *runtime_config.json* file, which
 will be available on Unix systems (~/.local/share/pgadmin/),
 on Mac OS X (~/Library/Preferences/pgadmin),
 and on Windows (%APPDATA%/pgadmin).
+
+
+Auto-Update Feature for pgAdmin 4 Desktop
+*****************************************
+
+pgAdmin 4's desktop application includes an automated update system built using Electron's ``autoUpdater`` module. This feature enables users to receive and install updates seamlessly, ensuring they always have access to the latest features and security fixes.
+
+Supported Platforms
+===================
+
+- **macOS:** Fully supported with automatic updates enabled by default
+- **Windows:** Not supported
+- **Linux:** Not supported
+
+Update Process Overview
+=======================
+
+1. **Check for Updates:**
+   
+   - Automatic check on application startup
+   - Manual check available via pgAdmin 4 menu > Check for Updates
+   - Uses Electron's ``autoUpdater`` API to query update server
+
+2. **Download Process:**
+   
+   - Updates download automatically when detected
+   - Progress shown via notifications
+   - Background download prevents interruption of work
+
+3. **Installation Flow:**
+   
+   - User prompted to restart when update ready
+   - Update applied during application restart
+
+Technical Architecture
+======================
+
+1. **Main Process (runtime/src/js/pgadmin.js)**
+
+   Handles core update functionality:
+
+   .. code-block:: javascript
+
+      autoUpdater.on('checking-for-update', () => {
+        misc.writeServerLog('checking for updates...');
+      });
+
+      autoUpdater.on('update-available', () => {
+        setConfigAndRefreshMenu('update-available');
+        misc.writeServerLog('Update downloading...');
+        pgAdminMainScreen.webContents.send('appUpdateNotifier', {update_downloading: true});
+      });
+
+2. **Renderer Process (web/pgadmin/static/js/BrowserComponent.jsx)**
+
+   Manages user interface updates:
+
+   .. code-block:: javascript
+
+      if (window.electronUI?.appUpdateNotifier) {
+        window.electronUI.appUpdateNotifier((data) => {
+          if (data.update_downloading) {
+            appUpdateNotifier('Update downloading...', 'info', 10000);
+          } else if (data.update_downloaded) {
+            appUpdateNotifier(UPDATE_DOWNLOADED_MESSAGE, 'warning', null, 
+              'Update downloaded', installUpdate, 'update_downloaded');
+          }
+        });
+      }
+
+3. **Update Server Communication**
+
+   - Configures update feed URL based on version information
+   - Handles server response validation
+   - Manages error conditions
+
+User Interface Components
+=========================
+
+1. **Notification Types:**
+   
+   - Update available
+   - Download progress
+   - Update ready to install
+   - Error notifications
+
+2. **Menu Integration:**
+   
+   - Check for Updates option in pgAdmin 4 menu
+   - Update status indicators
+   - Restart to Update option when available
+
+Error Handling
+==============
+
+The system includes comprehensive error handling:
+
+1. **Network Errors:**
+   
+   - Connection timeouts
+   - Download failures
+   - Server unavailability
+
+2. **Installation Errors:**
+   
+   - Insufficient disk space
+   - Permission issues
+   - Corrupted downloads
+
+3. **Recovery Mechanisms:**
+   
+   - Fallback to manual update
+   - Error reporting to logs
+
+Security Considerations
+=======================
+
+The update system implements several security measures:
+
+1. **Secure Communication:**
+   
+   - HTTPS for update checks
+   - Encrypted download process
+   - Protected update metadata
+
+Platform-Specific Notes
+=======================
+
+1. **macOS:**
+   
+   - Uses native update mechanisms
+   - Requires signed packages
+
+References
+==========
+
+- `Electron autoUpdater API Documentation <https://www.electronjs.org/docs/latest/api/auto-updater>`_

pkg/mac/README.md

@@ -31,11 +31,15 @@ Either build the sources or get them from macports or similar:
    *notarization.conf* and set the values accordingly. Note that notarization
    will fail if the code isn't signed.
 
-4. To build, go to pgAdmin4 source root directory and execute:
+4. To build only DMG file, go to pgAdmin4 source root directory and execute:
 
        make appbundle
+
+   To build both DMG and ZIP files, go to pgAdmin4 source root directory and execute:
+
+       make appbundle BUILD_OPTS="--zip"
        
    This will create the python virtual environment and install all the required
    python modules mentioned in the requirements file using pip, build the
-   runtime code and finally create the app bundle and the DMG in *./dist*
+   runtime code and finally create the app bundle and the DMG and/or ZIP in *./dist*
    directory.

pkg/mac/build-functions.sh

@@ -386,6 +386,24 @@ _codesign_bundle() {
              -i org.pgadmin.pgadmin4 \
              --sign "${DEVELOPER_ID}" \
              "${BUNDLE_DIR}"
+
+    echo "Verifying the signature from bundle dir..."
+    codesign --verify --deep --verbose=4 "${BUNDLE_DIR}"
+}
+
+_create_zip() {
+    ZIP_NAME="${DMG_NAME%.dmg}.zip"
+    echo "ZIP_NAME: ${ZIP_NAME}"
+
+    echo "Compressing pgAdmin 4.app in bundle dir into ${ZIP_NAME}..."
+    ditto -c -k --sequesterRsrc --keepParent "${BUNDLE_DIR}" "${ZIP_NAME}"
+
+    if [ $? -ne 0 ]; then
+        echo "Failed to create the ZIP file. Exiting."
+        exit 1
+    fi
+
+    echo "Successfully created ZIP file: ${ZIP_NAME}"
 }
 
 _create_dmg() {
@@ -427,8 +445,57 @@ _codesign_dmg() {
              "${DMG_NAME}"
 }
 
+_notarize_zip() {
+    if [ "${CODESIGN}" -eq 0 ]; then
+        return
+    fi
+
+    echo "Uploading ZIP for Notarization ..."
+    STATUS=$(xcrun notarytool submit "${ZIP_NAME}" \
+                              --team-id "${DEVELOPER_TEAM_ID}" \
+                              --apple-id "${DEVELOPER_USER}" \
+                              --password "${DEVELOPER_ASP}" 2>&1)
+
+    echo "${STATUS}"
+
+    # Get the submission ID
+    SUBMISSION_ID=$(echo "${STATUS}" | awk -F ': ' '/id:/ { print $2; exit; }')
+    echo "Notarization submission ID: ${SUBMISSION_ID}"
+
+    echo "Waiting for Notarization to be completed ..."
+    xcrun notarytool wait "${SUBMISSION_ID}" \
+                 --team-id "${DEVELOPER_TEAM_ID}" \
+                 --apple-id "${DEVELOPER_USER}" \
+                 --password "${DEVELOPER_ASP}"
+
+    # Print status information
+    REQUEST_STATUS=$(xcrun notarytool info "${SUBMISSION_ID}" \
+                 --team-id "${DEVELOPER_TEAM_ID}" \
+                 --apple-id "${DEVELOPER_USER}" \
+                 --password "${DEVELOPER_ASP}" 2>&1 | \
+            awk -F ': ' '/status:/ { print $2; }')
+
+    if [[ "${REQUEST_STATUS}" != "Accepted" ]]; then
+        echo "Notarization failed."
+        exit 1
+    fi
+
+    # Staple the notarization
+    echo "Stapling the notarization to the pgAdmin 4 app..."
+    if [[ "${ZIP_NAME##*.}" == "zip" ]]; then
+        xcrun stapler staple ${BUNDLE_DIR}
+        ditto -c -k --keepParent ${BUNDLE_DIR} ${ZIP_NAME}
+    fi
+
+    if [ $? != 0 ]; then
+            echo "ERROR: could not staple ${ZIP_NAME}"
+            exit 1
+    fi
+
+    echo "Notarization completed successfully."
+}
 
-_notarize_pkg() {
+_notarize_dmg() {
     if [ "${CODESIGN}" -eq 0 ]; then
         return
     fi

pkg/mac/build.sh

@@ -57,6 +57,32 @@ if [ "${PGADMIN_PYTHON_VERSION}" == "" ]; then
     export PGADMIN_PYTHON_VERSION=3.13.1
 fi
 
+# Initialize variables
+CREATE_ZIP=0
+CREATE_DMG=1
+
+# Parse command line arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --zip)
+            CREATE_ZIP=1
+            shift
+            ;;
+        --help)
+            echo "Usage: $0 [OPTIONS]"
+            echo "Options:"
+            echo "  --zip         Create both ZIP and DMG files"
+            echo "  --help        Display this help message"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            echo "Use --help for usage information"
+            exit 1
+            ;;
+    esac
+done
+
 # shellcheck disable=SC1091
 source "${SCRIPT_DIR}/build-functions.sh"
 
@@ -69,6 +95,16 @@ _complete_bundle
 _generate_sbom
 _codesign_binaries
 _codesign_bundle
-_create_dmg
-_codesign_dmg
-_notarize_pkg
+
+# Handle ZIP creation if requested
+if [ "${CREATE_ZIP}" -eq 1 ]; then
+    _create_zip
+    _notarize_zip
+fi
+
+# Handle DMG creation if not disabled
+if [ "${CREATE_DMG}" -eq 1 ]; then
+    _create_dmg
+    _codesign_dmg
+    _notarize_dmg
+fi