5.4 KiB
Upgrades and migration
This guide covers changes that need operator action when moving to RustProxy 0.34.0 and the included Nginx Proxy Manager importer. For ordinary package upgrades, first follow Installation and updates.
Before changing versions
- Record installed version, platform, current listener binds and external certificate paths.
- Create a password-encrypted off-host backup and confirm its password is available; separately copy external cert/key and integration state.
- Verify the target source and dependencies, compile and run tests on a staging copy when possible.
- Read release notes for cache compatibility, configuration changes, API token permissions and listeners requiring restart.
- Update with a maintenance window. Test production DNS, TLS, Vhost routes, access, cache behavior, PHP, Docker, Streams, logging and backup recovery before considering the upgrade complete.
A managed install uses update.sh; an unmanaged source-tree install must follow the supplied stopped upgrade path. Never overwrite an active database by extracting a ZIP over live private data. RustProxy normally applies forward SQLite schema migrations as needed; do not manually edit internal migration tables.
Notable compatibility points
| Change area | What to review |
|---|---|
| 0.34.0 cache | Operational Vhost saves aim to retain compatible HOT/COLD cache. Content-affecting changes invalidate a scope; older disk cache objects can require refilling. Validate actual behavior before rollout. |
| 0.34.0 Web Server | sendfile=auto is an optional Linux cleartext HTTP/1.1 path; default is off. No existing service needs to enable it. |
| 0.32.x origin protocols | Legacy backend http2 remains compatible on TLS (H2/H1) and H2C for plain HTTP. New strict h2 must be set explicitly. |
| 0.33.x Overview | Dashboard presets/layouts are per administrator, independent from Vhost configuration; existing preferences should be retained and new widgets may remain hidden. |
| Certificate API grants | Older broad/reload-only credentials can exist after additive migration; replace them with explicit certificate-ID allowlists and least privilege. |
| PHP-FPM | Distinct applications with different PHP INI overrides need separate external FPM pools and a worker restart; RustProxy cannot isolate FPM workers itself. |
| Legacy custom root location | A former untouched synthetic / location may normalize into the main Vhost fallback; a deliberately customized / rule remains an override. |
| External Certbot files | File-backed certificate paths stay external; backups and restores do not include those bytes. Check symlink and permission changes after renewal. |
Restore of configuration history changes only configuration, not a full application state snapshot. See Backup for disaster recovery.
Nginx Proxy Manager (NPM) import
The included scripts/migration/migrate_npm.py reads NPM's SQLite database and prepares RustProxy Vhosts. It does not modify NPM or migrate its private TLS keys. Keep migrate_npm.py and its two sibling helper modules together when running outside this source checkout.
What can migrate: NPM proxy-host domain names, upstream scheme/host/port, basic enabled state, WebSocket and force-HTTPS policy, and supported frontend listener selection. The importer reports more complex access lists, custom Nginx locations/directives, caching, exploit rules and certificate details for manual review. Private/backend origin policy and upstream TLS verification must be explicitly checked after import.
Dry run first
Locate the NPM SQLite database (often /data/database.sqlite inside its container). Back up its live consistent database before reading it; SQLite WAL may contain uncheckpointed changes.
python3 scripts/migration/migrate_npm.py \
--database /path/to/npm/database.sqlite \
--rustproxy https://rustproxy.example.net:9090
The default invocation creates npm-migration-plan.json with planned additions/skips; no write happens without --apply. Enter admin credentials through the prompt or secure environment, and use a trusted server certificate. The optional --ca-file supports a private CA; --insecure-admin-tls is a deliberate local/test exception, not a recommended setting for ordinary production automation.
Review each conflicting hostname, missing HTTPS listener/certificate, custom Nginx directive and backend policy. Explicit listener selection is possible with --http-listener and --https-listener.
Apply after reviewing the plan
python3 scripts/migration/migrate_npm.py \
--database /path/to/npm/database.sqlite \
--rustproxy https://rustproxy.example.net:9090 \
--apply
The migration writes through RustProxy's revisioned administration API, so it should not silently overwrite a newer config save. Test each imported domain and assign actual RustProxy certificates manually. Keep NPM available for rollback until the imported configuration is verified.
Unsupported or very old configurations
Do not assume arbitrary old Nginx config files, plugin-specific JSON, unmanaged data directory layouts or incompatible backup formats migrate automatically. Follow the original release notes or restore on an isolated older version first, then upgrade in controlled steps. Use the current API schema rather than undocumented JSON keys. For problems see Troubleshooting.