Upgrade Erde

This guide upgrades an existing Erde installation to a newer version by running the new installer. The same package handles both deployment shapes — Windows Service and IIS — and applies any pending database migrations the first time the upgraded server starts.

Before you start

• Role required: Local administrator on the Erde server (the installer needs elevation).
• Prerequisites: A working Erde installation with its first-run setup completed, and the new Erde-Setup.msi package.

Back up first

An upgrade replaces the application files and then applies database migrations automatically. Migrations change the schema and are not reversed if you reinstall an older package. Take a full backup — both databases, the appsettings.Production.json file, and the file-storage folder — before you proceed. See Back up and restore.

Steps

1. Verify that you have a current backup of the two databases (erde_platform and erde_app), the configuration file C:\Program Files\Erde\api\appsettings.Production.json, and the file-storage folder C:\ProgramData\Erde\storage\. See Back up and restore.

2. Confirm a valid license is active. On startup the server skips all migrations and seeding when no valid license is present, so the upgraded server will not apply the new schema until it is licensed. See Licensing.

3. Run the new Erde-Setup.msi on the machine that already has the previous version. Re-running the installer performs a major upgrade — there is no separate "update" mode. During the upgrade the installer:

   Step	What happens
   Stop	The existing Erde service is stopped (or the IIS site is stopped).
   Remove	The old application files are removed.
   Install	The new application files are installed.
   Start	The service is created and started (or the IIS site is restarted).

4. Wait for the server to finish its first start after the upgrade. Because appsettings.Production.json already exists, the server boots in normal mode (no setup wizard) and applies any new migrations automatically on startup. The first start after an upgrade can take longer than usual while migrations run.

5. Confirm the service is running and the application responds:

   Get-Service Erde

What the upgrade preserves

The installer does not track the files that hold your configuration and data, so they survive every upgrade:

File or folder	Why it is preserved
appsettings.Production.json	Created by the setup wizard, not by the installer. Holds the database connection strings and the JWT, AES, and token-hash keys. Never overwritten.
license.bin	Not tracked by the installer (written during license activation). Preserved automatically.
C:\ProgramData\Erde\storage\	File-storage blobs — user data, not managed by the installer.

The shipped appsettings.json (placeholder defaults), the application DLLs and executables, the Blazor client files, and web.config (IIS only) are all replaced with the new versions.

How migrations are applied

Migrations run as part of normal server startup — there is no separate migration command to run. The two databases (erde_platform, owned by the Platform database context, and erde_app, owned by the Application database context) are each migrated to their latest schema.

The diagram below shows the on-startup sequence after an upgrade.

For each database context, the server counts pending migrations. If none are pending it records that the database is up to date and continues. If there are pending migrations it applies them with standard Entity Framework Core migrate-to-latest behavior. Each migration runs once; subsequent restarts find nothing pending and start quickly. Migration history is tracked in the migrations table in the system schema of each database.

There is no automatic downgrade. A major upgrade reverts the application files, but migrations already applied to erde_platform and erde_app are not reversed. If an upgrade leaves a database in a state you need to undo, the documented recovery is to restore from a backup taken before the upgrade — which is why the backup in step 1 is required.

Result

The server runs the new version, both databases are migrated to the matching schema, and your configuration, license, and uploaded files are unchanged. Get-Service Erde reports the Erde service as running, and the application responds on its configured port (default 5000).

Troubleshooting

Symptom	Cause	Resolution
Windows reports error 1053 (Timeout) on the first start after the upgrade	Migrations run on first start and can exceed Windows' default service start timeout	The service keeps running and completes startup. Wait 60–90 seconds, then confirm with Get-Service Erde. Subsequent starts are fast because migrations run once.
API requests return HTTP 451 and the client shows a license overlay after the upgrade	No valid license is active, so the server skipped all migrations and seeding	Activate a valid license, then restart the service so migrations apply. See Licensing.
The setup wizard appears instead of the upgraded application	appsettings.Production.json is missing from C:\Program Files\Erde\api\, so the server entered first-run setup mode	Restore the preserved appsettings.Production.json from your backup into the api folder, then restart the service.
The service will not start after the upgrade	The database server is unreachable, the configured port is in use, or configuration is missing	Confirm the database server is running, check the port with netstat -an, and verify appsettings.Production.json is present.

Related

• Back up and restore
• Install with the MSI
• Database setup
• Licensing