Upgrading Portway

An upgrade replaces the application files and keeps configuration and databases.

Find your current version ​

Windows and Linux releases include .version.txt with the release version. Bug reports reference it.

Steps ​

1. Read the release notes ​

The GitHub release notes list breaking changes, migration steps and new configuration.

2. Back up the installation ​

• appsettings.json and appsettings.overrides.json
• auth.db, mcp.db and portway.key
• .env on Linux, which contains PORTWAY_ENCRYPTION_KEY
• environments/
• endpoints/
• .core/
• The file storage directory (FileStorage:StorageDirectory, default storage/files)

3. Stop the application ​

sudo systemctl stop portway

Stop-WebAppPool -Name "PortwayAppPool"

docker compose down

Stopping resets the in-memory cache and rate limit state.

4. Replace the application files ​

Linux package: install the newer .deb or .rpm package. Configuration file handling: Package upgrades.

Linux archive and IIS: extract the release over the existing directory without overwriting appsettings.json, environments/ and endpoints/.

Docker:

docker compose pull && docker compose up -d

5. Apply configuration changes ​

Apply the configuration changes from the release notes to appsettings.json and the environment files.

6. Start and verify ​

• GET /health/live returns Alive
• Endpoints respond in a test environment