From 984529bc7940ef30f62469c6b944c396469c75f0 Mon Sep 17 00:00:00 2001 From: Sebastian Almberg <83243306+Sebbeben@users.noreply.github.com> Date: Tue, 3 Feb 2026 11:55:53 +0100 Subject: [PATCH] Add Update Manager documentation - Add comprehensive update_manager.md with feature overview - Document CLI commands (partdb:update, partdb:maintenance-mode) - Document web interface and permissions - Add security considerations and troubleshooting - Update console_commands.md with new commands --- docs/usage/console_commands.md | 8 ++ docs/usage/update_manager.md | 170 +++++++++++++++++++++++++++++++++ 2 files changed, 178 insertions(+) create mode 100644 docs/usage/update_manager.md diff --git a/docs/usage/console_commands.md b/docs/usage/console_commands.md index b42bb757..576b3314 100644 --- a/docs/usage/console_commands.md +++ b/docs/usage/console_commands.md @@ -50,6 +50,14 @@ docker exec --user=www-data partdb php bin/console cache:clear * `php bin/console partdb:currencies:update-exchange-rates`: Update the exchange rates of all currencies from the internet +## Update Manager commands + +{: .note } +> The Update Manager is an experimental feature. See the [Update Manager documentation](update_manager.md) for details. + +* `php bin/console partdb:update`: Check for and perform updates to Part-DB. Use `--check` to only check for updates without installing. +* `php bin/console partdb:maintenance-mode`: Enable, disable, or check the status of maintenance mode. Use `--enable`, `--disable`, or `--status`. + ## Installation/Maintenance commands * `php bin/console partdb:backup`: Backup the database and the attachments diff --git a/docs/usage/update_manager.md b/docs/usage/update_manager.md new file mode 100644 index 00000000..43fe2c94 --- /dev/null +++ b/docs/usage/update_manager.md @@ -0,0 +1,170 @@ +--- +title: Update Manager +layout: default +parent: Usage +--- + +# Update Manager (Experimental) + +{: .warning } +> The Update Manager is currently an **experimental feature**. It is disabled by default while user experience data is being gathered. Use with caution and always ensure you have proper backups before updating. + +Part-DB includes an Update Manager that can automatically update Git-based installations to newer versions. The Update Manager provides both a web interface and CLI commands for managing updates, backups, and maintenance mode. + +## Supported Installation Types + +The Update Manager currently supports automatic updates only for **Git clone** installations. Other installation types show manual update instructions: + +| Installation Type | Auto-Update | Instructions | +|-------------------|-------------|--------------| +| Git Clone | Yes | Automatic via CLI or Web UI | +| Docker | No | Pull new image: `docker-compose pull && docker-compose up -d` | +| ZIP Release | No | Download and extract new release manually | + +## Enabling the Update Manager + +By default, web-based updates and backup restore are **disabled** for security reasons. To enable them, add these settings to your `.env.local` file: + +```bash +# Enable web-based updates (default: disabled) +DISABLE_WEB_UPDATES=0 + +# Enable backup restore via web interface (default: disabled) +DISABLE_BACKUP_RESTORE=0 +``` + +{: .note } +> Even with web updates disabled, you can still use the CLI commands to perform updates. + +## CLI Commands + +### Update Command + +Check for updates or perform an update: + +```bash +# Check for available updates +php bin/console partdb:update --check + +# Update to the latest version +php bin/console partdb:update + +# Update to a specific version +php bin/console partdb:update v2.6.0 + +# Update without creating a backup first +php bin/console partdb:update --no-backup + +# Force update without confirmation prompt +php bin/console partdb:update --force +``` + +### Maintenance Mode Command + +Manually enable or disable maintenance mode: + +```bash +# Enable maintenance mode with default message +php bin/console partdb:maintenance-mode --enable + +# Enable with custom message +php bin/console partdb:maintenance-mode --enable "System maintenance until 6 PM" +php bin/console partdb:maintenance-mode --enable --message="Updating to v2.6.0" + +# Disable maintenance mode +php bin/console partdb:maintenance-mode --disable + +# Check current status +php bin/console partdb:maintenance-mode --status +``` + +## Web Interface + +When web updates are enabled, the Update Manager is accessible at **System > Update Manager** (URL: `/system/update-manager`). + +The web interface shows: +- Current version and installation type +- Available updates with release notes +- Precondition validation (Git, Composer, Yarn, permissions) +- Update history and logs +- Backup management + +### Required Permissions + +Users need the following permissions to access the Update Manager: + +| Permission | Description | +|------------|-------------| +| `@system.show_updates` | View update status and available versions | +| `@system.manage_updates` | Perform updates and restore backups | + +## Update Process + +When an update is performed, the following steps are executed: + +1. **Lock** - Acquire exclusive lock to prevent concurrent updates +2. **Maintenance Mode** - Enable maintenance mode to block user access +3. **Rollback Tag** - Create a Git tag for potential rollback +4. **Backup** - Create a full backup (optional but recommended) +5. **Git Fetch** - Fetch latest changes from origin +6. **Git Checkout** - Checkout the target version +7. **Composer Install** - Install/update PHP dependencies +8. **Yarn Install** - Install frontend dependencies +9. **Yarn Build** - Compile frontend assets +10. **Database Migrations** - Run any new migrations +11. **Cache Clear** - Clear the application cache +12. **Cache Warmup** - Rebuild the cache +13. **Maintenance Off** - Disable maintenance mode +14. **Unlock** - Release the update lock + +If any step fails, the system automatically attempts to rollback to the previous version. + +## Backup Management + +The Update Manager automatically creates backups before updates. These backups are stored in `var/backups/` and include: + +- Database dump (SQL file or SQLite database) +- Configuration files (`.env.local`, `parameters.yaml`, `banner.md`) +- Attachment files (`uploads/`, `public/media/`) + +### Restoring from Backup + +{: .warning } +> Backup restore is a destructive operation that will overwrite your current database. Only use this if you need to recover from a failed update. + +If web restore is enabled (`DISABLE_BACKUP_RESTORE=0`), you can restore backups from the web interface. The restore process: + +1. Enables maintenance mode +2. Extracts the backup +3. Restores the database +4. Optionally restores config and attachments +5. Clears and warms up the cache +6. Disables maintenance mode + +## Troubleshooting + +### Precondition Errors + +Before updating, the system validates: + +- **Git available**: Git must be installed and in PATH +- **No local changes**: Uncommitted changes must be committed or stashed +- **Composer available**: Composer must be installed and in PATH +- **Yarn available**: Yarn must be installed and in PATH +- **Write permissions**: `var/`, `vendor/`, and `public/` must be writable +- **Not already locked**: No other update can be in progress + +### Stale Lock + +If an update was interrupted and the lock file remains, it will automatically be removed after 1 hour. You can also manually delete `var/update.lock`. + +### Viewing Update Logs + +Update logs are stored in `var/log/updates/` and can be viewed from the web interface or directly on the server. + +## Security Considerations + +- **Disable web updates in production** unless you specifically need them +- The Update Manager requires shell access to run Git, Composer, and Yarn +- Backup files may contain sensitive data (database, config) - secure the `var/backups/` directory +- Consider running updates during maintenance windows with low user activity