Upgrading and Maintenance
Relevant source files
The following files were used as context for generating this wiki page:
The upgrading and maintenance of the Nextcloud CAD Viewer application involves managing both PHP-based backend dependencies and Node.js-based frontend assets. This process ensures compatibility with the latest Nextcloud releases (currently targeted at Nextcloud 33) and incorporates updates from the upstream CAD rendering library, @mlightcad/cad-viewer.
This guide outlines the standard procedures for environment maintenance, dependency updates, and troubleshooting common operational issues. For initial setup instructions, refer to the Installation Guide.
Dependency Management
The project relies on two distinct package managers: Composer for the PHP backend and NPM for the Vue.js frontend. Maintenance requires keeping these ecosystems synchronized and compatible with the target environment.
Frontend Dependencies
The frontend is built using Vue 3 and Element Plus. A critical maintenance requirement is the use of the --legacy-peer-deps flag during installation to resolve peer dependency conflicts inherent in the @mlightcad packages.
| Package | Version | Purpose |
|---|---|---|
@mlightcad/cad-viewer | 1.5.0 | Core CAD rendering engine |
vue | 3.5.34 | Frontend framework |
element-plus | 2.13.6 | UI component library |
Sources: package.json:34-47, AGENTS.md:21-25
Backend Dependencies
The backend requires PHP 8.2+ and follows Nextcloud's coding standards. Maintenance involves periodic updates to development tools like Psalm, PHPStan, and PHPUnit to ensure code quality and security.
Sources: composer.json:14-25, README.md:20-22
Upgrading Upstream CAD Viewer
When new versions of the mlightcad/cad-viewer are released, the Nextcloud app must be updated to leverage new features or bug fixes.
Upgrade Workflow
The following diagram illustrates the lifecycle of an upgrade from the upstream dependency through to a production build.
The upgrade workflow ensures that the vendor-provided CAD logic is properly integrated into the Nextcloud environment before deployment.
Sources: README.md:129-145, AGENTS.md:21-25
Maintenance Scripts
Standardized scripts are provided in package.json and composer.json to facilitate routine maintenance tasks:
| Command | Action |
|---|---|
npm run build | Compiles production-ready frontend assets |
npm run lint | Checks frontend code for style and syntax issues |
composer psalm | Performs static analysis on the PHP backend |
composer cs:fix | Automatically fixes PHP coding standard violations |
Sources: package.json:13-20, composer.json:36-40
Environment Maintenance
Maintaining the server environment is crucial for the performance of CAD rendering, which is resource-intensive due to WebGL and large file processing.
Server Configuration Updates
Administrators should periodically verify that PHP and web server limits are adjusted to handle large CAD files.
; Recommended php.ini settings for maintenance
upload_max_filesize = 500M
post_max_size = 500M
memory_limit = 1024M
max_execution_time = 300
Sources: wiki/Installation-Guide.md:162-167, wiki/Troubleshooting.md:225-230
Cache Management
Routine maintenance should include clearing Nextcloud caches, especially after an app upgrade or theme update, to prevent stale assets from causing display issues.
# Recommended maintenance commands
sudo -u www-data php /var/www/nextcloud/occ maintenance:repair
sudo -u www-data php /var/www/nextcloud/occ maintenance:update:theme
Sources: wiki/Installation-Guide.md:173-177, wiki/Troubleshooting.md:20-25
Troubleshooting Maintenance Issues
The maintenance process may encounter several failure points, particularly during the build or enable phases.
Build Failures
If npm run build fails after a dependency update, a clean reinstall is the standard recovery procedure.
This sequence ensures that no corrupted local artifacts interfere with the upgrade process.
Sources: wiki/Troubleshooting.md:38-45, AGENTS.md:21-25
Permission Maintenance
Ensuring the web server (e.g., www-data) retains ownership of the cad_viewer directory is a recurring requirement, particularly after manual git operations or archive extractions.
Sources: wiki/Installation-Guide.md:207-214, README.md:53-55
Conclusion
Maintenance of the Nextcloud CAD Viewer is a dual-track process requiring attention to both the PHP backend and the Vue frontend. By consistently using standardized build commands and adhering to specific installation flags like --legacy-peer-deps, developers and administrators can ensure the viewer remains stable and compatible with the latest Nextcloud releases.