This document covers upgrading the PowerShell Universal application.
The Universal application binaries can generally be upgraded without having to change the configuration or database manually. This document will cover how to upgrade the application and some caveats to be aware of in regards to configuration and data persistence.
Data is persisted in a LiteDB database with a default location of %ProgramData%\UniversalAutomation\database.db. The database will not be deleted during an upgrade of any kind. Any schema updates to the database will happen the first time you start up the new version of Universal. You may wish to backup your database before performing an upgrade.
Configuration files are stored by default in %ProgramData%\UniversalAutomation. Configuration files may be updated or transformed during an update. This will happen the first time that the new version of Universal server is started. You may wish to backup your configuration files before performing an upgrade.
If you are using git, changes to the Universal files will be synchronized after the server starts up.
The appsettings.json file that is included in the application installation directory will be overwritten during upgrades. To avoid losing your settings in this file, consider installing it into the %ProgramData%\PowerShellUniversal folder. Universal will look at this folder first for configuration settings.
The web.config file that is included in the application installation directory will be overwritten during upgrades. If you have moved your web.config file to an alternate location, it will not be overwritten. When creating an IIS website, you can simply include the web.config file in the web app's directory and have the binaries stored in a different location.
New versions of Universal may include new versions of Universal Dashboard Frameworks or Components. By default, these components and frameworks are deployed to %ProgramData%\PowerShellUniversal during startup of the Universal server. During an upgrade, these files are not deleted. This ensures that dashboards will continue to run on the previous dashboard framework and component versions.
You should have multiple versions of the dashboard frameworks and components available when you start the new version of Universal.
By default, new dashboards are set to always use the latest version of the dashboard framework. You can chose to set it to a specific version if you would like but will have to manually change the version during an upgrade.
Repository
Most of the settings for PowerShell Universal are stored within the repository folder. By default, this is in %ProgramData%\UniversalAutomation\Repository. While the upgrade should not affect these files, you may want to backup the files before upgrading.
Always ensure to run Unblock-File on Windows to unblock all the files extracted the ZIP. If you do not, PowerShell Universal will not function properly.
When upgrading an manual ZIP file installation, you will need to stop the application, delete the entire binary folder and replace it with the new binary folder. When you start the new version of Universal, new dashboard frameworks and components will be deployed and the existing database will be loaded.
To upgrade using the MSI, you can simply run the new version of the MSI. The MSI is setup to always perform a major upgrade. This means it will stop and remove the service, delete the entire installation directory, reinstall with the new files and then install and start the new service.
You will want to follow the guide on data and configuration persistence above to ensure all your settings are saved.
If you have configured a service account for your MSI installation, you will need to set the service account after upgrading.
When upgrading with IIS, you will need to first stop your application pool to ensure that the binaries used by IIS are no longer in use and then replace the binaries with the new ones. Ensure that you follow the configuration persistence recommendations above with regards to the web.config file.
PowerShell Universal uses LiteDB to store jobs, app tokens, identities and git sync history. The original version of LiteDB included with PSU is version 4. We will be moving to version 5 in a future version. We have added version 5 support but are not yet upgrading users databases. You can choose to upgrade your database to version 5 by adjusting your connection string to perform an upgrade on the database. We suggest backing up your database file before doing so.
In appsettings.json, you will need to change the database type to LiteDBv5 and add the upgrade parameter to the connection string.
This page provides installation and configuration information for Docker.
Our docker image is available on Docker Hub. You can start it by pulling and then running with the default port bound.
Tag
Platform
1.3.0
linux/amd64
1.3.0-windowsservercore-1909
windows/amd64
To create a Docker image that can persist the Universal data, you can create a dockerfile like the one below.
This dockerfile exposes port 5000, creates a /data volume, sets configuration environment variables to store the Universal repository and database in the volume and then sets the Universal.Server as the entry point to the container.
You can run a build with the build command.
You can start the docker container with the run command and make sure to specify the volume to mount.
Installation instructions for PowerShell Universal.
You can use the PowerShell Universal PowerShell module to install the Universal server. To install the module, use Install-Module.
To install the Universal server, you can use Install-PSUServer.
You can configure the path that the server is stored in by using the -Path parameter.
You can add the PSU server to the PATH environment variable by use the -AddToPath parameter.
Once the server has been installed, you can use Start-PSUServer to start it.
You can specify the path to the executable using the -ExecutablePath parameter. If you have set the location of the server to -AddToPath with Install-PSUServer, Start-PSUServer should find the executable automatically.
You can install PowerShell Universal using the Chocolatey package. The package runs the MSI install. It will install Universal as a service and open a web browser after the install.
You can login with the "admin" user and any password.
You can install PowerShell Universal using Winget. It will run the MSI and install as a service.
You can also specify the --silent flag to prevent the installer from showing and the web browser from opening at the end of the install.
You can also download the ZIP from our Downloads page if you would like to xcopy deploy the files on Windows or Linux.
You can start Universal by unzipping the contents, unblocking the files and then executing Universal.Server.exe.
On Linux, start the process Universal.Server. You may need to chmod +x the file if it does not start.
See the Docker page.
The MSI install will create a PowerShell Universal service and open the admin console after installation.
Setting the SUPPRESBROWSER MSI property to true will prevent the browser from opening after installation.
At this point, Universal is up and running. Please consult other sections in this documentation for instructions on how to configure, secure, and start using PowerShell Universal. Happy Scripting!