{"id":21284972,"url":"https://github.com/iontelos/sum","last_synced_at":"2025-03-15T15:11:46.721Z","repository":{"id":259861492,"uuid":"879659935","full_name":"IonTeLOS/sum","owner":"IonTeLOS","description":"SUM - Simple Update Manager","archived":false,"fork":false,"pushed_at":"2024-10-28T20:39:50.000Z","size":116,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-22T05:14:32.173Z","etag":null,"topics":["application-repo","checksum","opensource","pyside6","python","software-update","sum","update-checker","updatemanager"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IonTeLOS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-28T10:21:18.000Z","updated_at":"2024-10-28T20:39:53.000Z","dependencies_parsed_at":"2024-10-28T13:46:54.258Z","dependency_job_id":"a46fee7f-6b44-4986-a6be-3ed01b8d3875","html_url":"https://github.com/IonTeLOS/sum","commit_stats":null,"previous_names":["iontelos/sum"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IonTeLOS%2Fsum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IonTeLOS%2Fsum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IonTeLOS%2Fsum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IonTeLOS%2Fsum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IonTeLOS","download_url":"https://codeload.github.com/IonTeLOS/sum/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243746201,"owners_count":20341203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["application-repo","checksum","opensource","pyside6","python","software-update","sum","update-checker","updatemanager"],"created_at":"2024-11-21T11:17:44.588Z","updated_at":"2025-03-15T15:11:46.688Z","avatar_url":"https://github.com/IonTeLOS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SUM - Simple Update Manager\n\n![SUM Icon](update_icon.png)\n\n**SUM** is a lightweight, intuitive, and powerful update manager designed to handle seamless updates for your standalone applications, particularly those developed with [PySide6](https://pypi.org/project/PySide6/). SUM empowers your applications to autonomously manage their updates by automatically downloading, installing, and verifying updates without disrupting the user experience.\n\n## 🎯 Key Features\n\n- **Automatic Update Checks:** Connect to your designated update server to check for newer versions.\n- **Interactive GUI Mode:** SUM provides an easy-to-follow interface, offering your users control over update timing.\n- **Seamless Installation:** Handles download, backup, and replacement of executables safely.\n- **Rollback Functionality:** If an update fails, SUM automatically restores the previous version, minimizing downtime.\n- **Flexible Compatibility:** Although optimized for PySide6 apps, SUM can manage updates for other standalone applications that do not require complex packaging systems (e.g., Debian packages).\n- **Checksum Verification:** Confirms the integrity of each downloaded update by verifying its checksum before installation.\n- **Cross-Platform:** SUM works on Linux, Windows, and macOS.\n\n## 💡 Getting Started\n\n### 🛠 Installation and Setup\n\nSUM is designed to be a standalone updater that any application can call to handle its own updates. To use SUM, follow these steps:\n\n1. **Build SUM as a Standalone Executable:**\n\n   Place the `sum.py` script alongside any necessary files (`dep.sh`, `update_icon.png`) and create a standalone executable using [PyInstaller](https://www.pyinstaller.org/):\n\n   ```bash\n   pyinstaller --onefile --add-data \"dep.sh:.\" --add-data \"update_icon.png:.\" sum.py\nThis command packages sum.py into a single executable while including the dep.sh script and the update icon.\n\nIntegrate SUM into Your Application:\n\nFrom within your application, call the SUM executable whenever you need to check for updates. Here's an example of how to do this in Python:\n\npython\nCopy code\nimport subprocess\nimport sys\nfrom pathlib import Path\n\ndef check_for_updates():\n    current_version = \"1.0.0\"\n    app_location = str(Path(__file__).resolve())\n    update_url = \"https://my-awesome-server.com/update\"\n\n    # Path to the SUM executable\n    sum_executable = Path(\"/path/to/sum_executable\")  # Update this path accordingly\n\n    # Command to run SUM\n    command = [\n        str(sum_executable),\n        \"--current_version\", current_version,\n        \"--current_location\", app_location,\n        \"--url\", update_url,\n        \"--interactive\"  # Optional: Enable GUI interactive mode\n    ]\n\n    # Execute SUM\n    subprocess.run(command)\n\nif __name__ == \"__main__\":\n    check_for_updates()\n    # Continue with the rest of your application\nReplace \"/path/to/sum_executable\" with the actual path to your SUM executable. This setup allows your application to delegate the update process to SUM seamlessly.\n\n📜 Command-Line Arguments\nSUM accepts several command-line arguments to customize the update process. Here's a breakdown of each argument:\n\n-v, --current_version (required)\nThe current version of the application to be updated, used to compare against the latest version available online.\n\n-f, --current_location (required)\nThe file path to the current executable of the app to be updated, allowing SUM to locate and replace it if an update is available.\n\n-u, --url (required)\nURL to check for the latest version and update files. Must be HTTPS unless it's a local network address.\n\n-n, --app-name\nCustom name for the application, which SUM will use in logs and notifications. If not provided, SUM uses the executable's basename.\n\n-i, --interactive\nEnables the interactive GUI mode, making the update process more user-friendly with progress bars and prompts.\n\n-e, --extras\nAdditional script commands to execute prior to the update process, allowing for pre-installation checks or custom configurations.\n\nCopy code\n## 📄 Update JSON Format\n\nFor SUM to correctly identify and handle updates, the JSON data hosted at your update URL must adhere to the following structure:\n\n### 🗂️ JSON Structure\n\n```json\n{\n    \"version\": \"1.0.1\",\n    \"platforms\": {\n        \"linux\": {\n            \"download_url\": \"https://example.com/download/linux/app_v1.0.1\",\n            \"checksum\": \"abc123def4567890abcdef1234567890abcdef1234567890abcdef1234567890\"\n        },\n        \"windows\": {\n            \"download_url\": \"https://example.com/download/windows/app_v1.0.1.exe\",\n            \"checksum\": \"123abc456def78901234567890abcdef1234567890abcdef1234567890abcdef\"\n        },\n        \"darwin\": {\n            \"download_url\": \"https://example.com/download/macos/app_v1.0.1\",\n            \"checksum\": \"789def012abc34567890abcdef1234567890abcdef1234567890abcdef123456\"\n        }\n    }\n}\n```\n\n📌 Field Descriptions\nversion (string, required):\nThe latest version of your application. This should follow semantic versioning (e.g., \"1.0.1\").\n\nplatforms (object, required):\nAn object containing platform-specific update information.\n\nlinux (object, required):\nInformation specific to Linux platforms.\n\ndownload_url (string, required):\nThe direct URL to download the updated executable for Linux.\n\nchecksum (string, optional):\nThe SHA-256 checksum of the downloadable file to verify its integrity.\n\n📝 Example Explanation\nversion: Indicates that the latest available version of the application is \"1.0.1\".\n\nplatforms: Contains update information tailored for each supported platform.\n\nlinux.download_url: Users on Linux will download the updated application from \"https://my-awsome-server.com/download/linux/app_v1.0.1\".\n\nlinux.checksum: The SHA-256 checksum \"abc123def4567890abcdef1234567890abcdef1234567890abcdef1234567890\" ensures the downloaded file hasn't been tampered with.\n\nSimilarly for Windows and Darwin.\n\n🔒 Security Considerations\nHTTPS URLs: Ensure all download_url links use HTTPS to maintain secure download channels.\n\nChecksum Verification: It's highly recommended to provide the checksum field for each platform to allow SUM to verify the integrity of the downloaded files, preventing potential tampering or corruption.\n\n✅ Validation\nBefore deploying your update JSON, validate its structure to ensure SUM can parse it correctly. You can use online JSON validators or tools like jq to check for syntax errors.\n\n```bash\njq . update.json\n## Replace update.json with your actual JSON file name\n```\n\n🌟 Additional Notes\nExtensibility: You can add additional platforms if needed by following the same structure.\n\nOptional Fields: While checksum is optional, providing it enhances security by ensuring file integrity.\n\nEnsure that the JSON file is accessible via the specified --url when running SUM.\n\n🚀 How to Use SUM\nOnce SUM is built and integrated into your application, you can invoke it as needed. Here's an example command to run SUM from your application:\n\nbash\nCopy code\n./sum --current_version \"1.0.0\" --current_location \"/path/to/app\" --url \"https://example.com/update\" --interactive\nIn interactive mode, SUM will prompt the user with a graphical dialog, providing the option to proceed with updates or dismiss the notification. If an update is found, SUM downloads and installs it in the background. The app also maintains a backup of the current executable and can automatically restore it if an update fails.\n\nExample: Calling SUM from a PySide6 Application\nHere's a more concrete example of how a PySide6 application can call SUM to handle its updates:\n```python\nimport subprocess\nimport sys\nfrom pathlib import Path\nfrom PySide6.QtWidgets import QApplication, QPushButton\n\ndef check_for_updates():\n    current_version = \"1.0.0\"\n    app_location = str(Path(sys.argv[0]).resolve())\n    update_url = \"https://my-awesome-server.com/update\"\n\n    # Path to the SUM executable\n    sum_executable = Path(\"/path/to/sum_executable\")  # Update this path accordingly\n\n    # Command to run SUM\n    command = [\n        str(sum_executable),\n        \"--current_version\", current_version,\n        \"--current_location\", app_location,\n        \"--url\", update_url,\n        \"--interactive\"  # Optional: Enable GUI interactive mode\n    ]\n\n    # Execute SUM\n    subprocess.run(command)\n\nif __name__ == \"__main__\":\n    app = QApplication(sys.argv)\n    window = QPushButton(\"Check for Updates\")\n    window.clicked.connect(check_for_updates)\n    window.show()\n    sys.exit(app.exec())\n```\n\nIn this example:\n\nButton Trigger: A button labeled \"Check for Updates\" is created. When clicked, it triggers the check_for_updates function.\nRunning SUM: The check_for_updates function constructs the command to run SUM with the necessary arguments and executes it using subprocess.run.\nSeamless Integration: This allows your PySide6 application to delegate the update process to SUM without disrupting the main application flow.\n⚠️ Compatibility Notes\nSUM is optimized for PySide6 applications, but it can work with other single-file executables as well. However, it is not compatible with applications that use system package managers, like Debian’s .deb packages. SUM is best suited for independent executables that are not managed by system-level packaging tools.\n\nSupported Platforms\nLinux (Debian 11+)\nWindows\nmacOS\n\n🛡 Security Considerations\nHTTPS Enforcement: SUM ensures that update URLs use HTTPS to maintain secure communication, except for local network addresses.\nChecksum Verification: Each downloaded update is verified using SHA-256 checksums to ensure file integrity and prevent tampering.\n🗂 Additional Dependencies\nTo ensure SUM’s functionality on various Linux distributions, it includes a dependency check script (dep.sh) that automatically installs required packages if missing. This script uses pkexec for privilege escalation if available; otherwise, it attempts to open x-terminal-emulator for password prompts.\n\ndep.sh Overview\nChecks for Required Libraries: Ensures that all necessary system libraries for running PySide6 applications are installed.\nAutomatic Installation: Installs missing dependencies using apt with elevated permissions.\nGraceful Handling: Continues to run the application even if some dependencies fail to install, logging warnings accordingly.\n\n📈 Logging and Monitoring\nSUM maintains a rotating log file (software_updates.log) located in the same directory as the executable. This log records all update events, including successes, failures, and any rollback actions taken.\n\n🌐 Project Links and Documentation\nFor more information, detailed documentation, and code examples, please visit our GitHub repository.\n\n🤝 Contributing\nContributions are welcome! If you encounter issues or have suggestions for improvements, feel free to open an issue or submit a pull request on GitHub.\n\n📜 License\nSUM is released under the MIT License.\n\nThank you for using SUM! We’re excited to help you keep your applications up-to-date with ease and reliability.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiontelos%2Fsum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiontelos%2Fsum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiontelos%2Fsum/lists"}