This document covers upgrading the PowerShell Universal application.
This document will cover the upgrade process for production PowerShell Universal instances. We will cover the following topics.
Data Backup
Upgrade Process
Upgrade Validation
The Universal application binaries can generally be upgraded without having to change the configuration or database manually, but we do recommend backups of production data.
PowerShell Universal uses a script-based configuration system alongside a database used for retention of entities such as app tokens, job history and identities. If possible, you will want to backup these items before running an upgrade for easy rollback in case an issue is encountered during validation.
Backing up the database ensures that all apptokens, job history, identities and database secrets are retained in the case of an upgrade failure. SQL databases also may adjust the schema of the database and may require a rollback of not only the data, but also the schema of the tables in the database.
By default, PowerShell Universal uses a single file database called LiteDB. Unless configured otherwise, the database is stored in %ProgramData%\UniversalAutomation. You should have a database.db and possibility a database-log.db. Both of these files should be backed up. The service must be stopped in order to backup the files.
When using SQL for persistence, backup the entire database (including schema). There isn't necessarily a need to stop the PowerShell Universal service when backing up the database but it may continue to write to the database (for example when running scheduled jobs) after the backup has been completed.
Scripts make up the main configuration data to backup when upgrading a production PowerShell Universal instance. For production, we recommend using a version control system. You can also take advantage of the built-in git integration. If you are using a two-way sync for PowerShell Universal git integration, consider tagging your git branch prior to the upgrade to allow for easy rollback to unexpected changes within the git repository.
Below are sections for each type of system upgrade and the steps that you should take based on how you originally installed PSU.
When installing via the MSI, you will want to follow the same backup procedures above.
You will want to back up the appsettings.json file stored in %ProgramData%\PowerShellUniversal. This file contains information such as port, data storage location and other server settings. Typically, the MSI will not make changes to this file once created. It will use the settings found for the upgraded version. That said, if necessary, the MSI will make changes to the appsettings file. These changes are considered breaking and will be listed in the changelog for the release.
When running an MSI upgrade, the PSU service is not uninstalled, and thus, the service account will still be set once the service starts up.
If you perform an uninstall and then an install using the MSI, then the service account will be removed.
Once all the configuration files and the database are backed up, you can run the new MSI installer. The installer may prompt for a restart of the machine if files are locked. The PSU MSI will uninstall all the files in the installation directory and install entirely new files.
Once the MSI has completed, you can navigate to your PowerShell Universal admin console to perform installation validation.
Below you will find information about upgrading an IIS install.
In addition to the files listed to backup above, you will also want to consider backing up your web.config file. If you have made no changes to this file, you do not need to back it up.
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.
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. To ensure that the upgrade works as expected, it's recommended to delete all the application files and then unzip the new ones into the same directory to avoid assembly conflicts.
As with any installation from a ZIP file, make sure that you run Get-ChildItem -Recurse | Unblock-File from an elevated command prompt across the PowerShell Universal files to ensure they can be executed properly.
Once you have copied the new files and unblocked them, start the app pool, navigate to the PowerShell Universal Admin Console and perform installation validation.
The Universal module can be used to upgrade installations of PowerShell Universal previously installed by the module.
Do not use the Universal module to upgrade instances installed via MSI.
Follow the backup procedures above and then perform the upgrade.
First, upgrade the local PowerShell Universal module and verify the expected version is installed.
Next, run Update-PSUServer to download and unzip the new PSU instance.
After the upgrade is complete, navigate to the PowerShell Universal Admin Console and begin upgrade validation.
Perform the necessary backup procedures and download the latest ZIP of PowerShell Universal.
Stop the PowerShell Universal service. Delete the existing PowerShell Universal application files. Extract the ZIP files to the same directory. Finally, run Unblock-File against the directory to ensure that PSU can execute properly. Always run this command as administrator.
After the upgrade is complete, navigate to the PowerShell Universal Admin Console and begin upgrade validation.
After running an upgrade, you should perform basic validation against your PSU server to ensure that it is fully functional.
Verify that there are no errors within the notification drop down. They may be a sign of issues during the upgrade.
Verify that all environments are listed in the Settings \ Environments page. Although upgrades may not necessarily cause a change in environments, restarting the PowerShell Universal service (without an environments.ps1 file) will cause PSU to rediscover environments. Updates to PowerShell outside of PSU may cause issues with PSU after it restarts.
Upgrades to PowerShell Universal may change assembly versions of DLLs shipped with the platform. This can cause other modules to fail to load. While this may not be obvious at first, you may consider taking an inventory of modules used in your platform to ensure that the versions are consistent before and after the upgrade to limit changes.
If you have installed a version of the Universal module outside of PowerShell Universal (for example, with Install-Module), you must make sure to update the module or it can conflict with the new one installed with PowerShell Universal.
The most common upgrade issues come due to changes in the dashboard framework. Dashboards can be complex and bug fixes or features can sometimes cause for certain user's dashboards while fixing issues pertaining to another user's dashboard. Please read the changelog before upgrading to understand the impact of changes made to the dashboard framework and consider testing the dashboard with development data before upgrading in production.
The most common upgrade issue is that Unblock-File is not called properly on the extracted files when performing an upgrade of a IIS ZIP install. Also make sure to run the Unblock-File command recursively and from within an administrative session.
Another command issue is extracting the files over the top of the existing files. This can cause assembly conflicts and puts the application in an unknown state. Follow the IIS upgrade documentation and delete the files before extracting them.
When new functionality is added to PowerShell Universal it is typically done using new cmdlets. If older versions of the PowerShell Universal module are installed on the system, it can cause conflicts with the one shipped within the installation media. Ensure that you have removed older versions of the Universal module if you encounter these errors.
This can happen if SQL schema upgrades are not being run during upgrades. If you set the RunMigrations setting to false in appsettings.json, you must run the migrations manually or the PowerShell Universal service will not function properly.
These changes can be visual or functional. Please ensure that you review the changelog for items that may be related to the change you are seeing. Consider posting the forums or opening a GitHub issue to see if the issue is as designed and if there is a viable workaround.
We make the best possible effort to support everyone's' dashboards without breaking changes. That said, every configuration is pretty unique so we are more than happy to address issues you may encounter. Please, just let us know.
The licensing model of PowerShell Universal provides licensed users the ability to upgrade to whatever is the newest version as long as they have an active perpetual or subscription license. If you attempt to upgrade a server that is no longer within the license window, the server will not function as expected. You will need to downgrade back to the previous version to restore functionality.
Additionally, you may encounter issues due to the PSU service restart. When the service starts, it verifies license subscription status. If it fails to do so, it may not be licensed properly and cause other issues. The root cause is typically networking issues while attempting to access the IronmanSoftware.com website for activation. Offline license keys do not contact the IMS website for activation and will not encounter this issue.
If you are upgrading from 2.x, you will have a couple of breaking changes.
For performance reasons, secret variables are no longer automatically included in environments. To use secret variables, use the new secret scope.
The UDv2 framework has been removed and is no longer supported. If you wish to use this framework, you can install it from the PowerShell Gallery.
If you are hosting in IIS, ensure that you install the .NET 6.0 hosting bundle.
PowerShell 7.2 or later is supported by PowerShell Universal v3.
In the PowerShell Universal installation directory, there you will find the DataMigrator.exe tool for moving data from a local LiteDB database to a SQL server database. It takes care of creating the dashboard, creating the schema and transferring data.
Although we only read data from LiteDB, we recommend backing it up before running the tool.
Once migrated, you will need to update the plugin setting within appsettings.json. Replace the UniversalAutomation.LiteDBv5 value with the string SQL. You can also set an environment variable to use the SQL plugin.
You'll also need to replace the connection string value with your SQL Data \ ConnectionString.
Similar to the plugin, you can use an environment variable instead of updating appsetings.json.
The step by step process is as follows:
Stop the PowerShell Universal service
Backup the database and repository
Run the data migration tool
Update the appsettings.json or environment variable to enable the SQL plugin and set the connection string.
Start the PowerShell Universal service
Once the service starts, it will be connected to SQL. Job data, identities, computers, and terminal instances will be stored in SQL.
If you are encountering issues with upgrades, you can use the --ContinueOnError flag to continue processing data even if an error is encountered. Typically, errors are the result of job history that may be missing a referential entity. LiteDB is document based while SQL is a relational database so some data may not translate perfectly.
Uninstall PowerShell Universal
Depending on how you installed PowerShell Universal, you will need to uninstall the application files.
If you installed using a provided ZIP file, you can simply stop the PowerShell Universal process or service and delete the folder you extracted to.
If you installed with the Windows MSI, uninstall the application from Add\Remove Programs.
The Universal module installs the application files to the following locations by default.
%ProgramData%\PowerShellUniversal
%HOME%/.PowerShellUniversal
Configuration files are stored in the repository folder. Once you have removed the application files, you can delete the configuration files. They are stored in the following locations by default:
%ProgramData%\PowerShellUniversal
%ProgramData%\UniversalAutomation
%HOME%/.PowerShellUniversal/
%HOME%/.PowerShellUniversal/
%AppData%\PowerShellUniversal
Removing the database depends on the database type used.
LiteDB databases are stored in a single file on the file system.
%ProgramData%\PowerShellUniversal\database.db
%HOME%/.PowerShellUniversal/database.db
SQL databases are stored on your SQL server and will require you to manually remove the database.
You may need to uninstall the IIS App Pool and Website when removing PowerShell Universal.
This page provides installation and configuration information for Docker.
NOTE: Note: Apple M1 devices: At the time of writing there are some issues on Apple M1 devices and, some ARM64/ARMv8 devices. Please review before proceeding.
Run the following command to confirm Docker is installed:
Example Output:
Docker Compose v1 uses the command docker-compose. As of June 2023 support ends for Docker Compose v1.
Docker Compose v2 uses the command docker compose.
Run one of the following commands to check Docker Compose is installed:
Docker Compose v1:
Docker Compose v2:
Example Output:
To ensure that Docker has the ability to pull and run container images run the following command:
Example Output:
The prebuilt version allows you to run all free and paid features of PowerShell Universal.
You can start the container by pulling the image and then running a container with the default port bound.
If port 5000 is unavailable on your host, this can be switched to another port.
e.g. Present on port 80
The docker run command will allow you to mount a volume for persistent storage. This needs to be mounted to the /root folder.
Mount a volume on container in Windows
The following command mounts the folder C:\docker\volumes\PSU to /root on your container
Mount a volume on Container on Mac and Linux
The following command mounts the folder /docker/volumes/PSU to /root on your container
The following command removes a stopped container named PSU
The following command stops a container named PSU
The --force flag can be used to remove a running container
Docker Compose allows you to use a yaml text file to standardize your build and script the deployment (or build) or multiple containers.
The default name for any compose file is docker-compose.yml it is recommended you use this as your compose filename.
The following compose file will run a Powershell Universal container in Windows
The following compose file will run a Powershell Universal container on Mac's and Linux
Using a Terminal shell, or PowerShell for Windows. cd to the directory with your docker-compose.yml script.
Run the following command
Example Output:
Using a Terminal shell, or PowerShell for Windows. cd to the directory with your docker-compose.yml script.
Run the following command
Example Output:
You can add Environment variables into your Compose Scripts. Below is an example of:
Setting a node name
Adding SQL persistance
Adding a SQL Connection String
In some cases, you may wish to build more features, modify, or hardcode Environment Variables into your container.
For that, you will need to Create a Dockerfile
NOTE: Dockerfiles' are case-sensitive and must start with a capital 'D'.
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.
From the path your Dockerfile is hosted in run the following command:
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.
To use SQL persistence, you can define the plugin and connection string as follows.
To properly support time zones on Linux when scheduling jobs, you will need to include the tzdata package in your dockerfile along with an environment variable that specifies the server time zone.
This has been a very basic "How get get started" which allows you to get started running or building PSU Containers. All souces for commands have been linked in the referances session.
https://docs.docker.com/engine/reference/commandline/run/
https://docs.docker.com/engine/reference/commandline/stop/
https://docs.docker.com/engine/reference/commandline/rm/
https://docs.docker.com/compose/
https://docs.docker.com/engine/reference/commandline/build/
Installation instructions for PowerShell Universal.
The MSI install will create a PowerShell Universal service. By default, PowerShell Universal will be listening on port 5000. You will be able to navigate to http://localhost:5000 and login with admin and password admin.
MSI downloads are available on our .
The following table contains the parameters you can specify if running msiexec against our MSI install for automation purposes.
| Parameter | Description | Default Value |
|---|
Below is an example of how to run msiexec.exe to install PowerShell Universal and provide parameters to the installer.
You can start Universal by unzipping the contents, unblocking the files and then executing Universal.Server.exe.
You can use the following command line on Linux to install and start 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.
If you run this command on Windows, a Windows service will be created and started on your machine. If you run this command on Linux, a systemd service will be created and started. If you run this command on Mac OS, the PowerShell Universal server will be downloaded and extracted.
Chocolatey packages for PowerShell Universal are usually available within a week of release but will not be available the day of a release.
You can login with the "admin" user and any password.
PowerShell Universal takes full advantage of PowerShell and the PowerShell SDK. It includes PowerShell scripts directly in the product. You will want to consider configuring antivirus to allow for execution of PowerShell scripts in PowerShell Universal.
The following directories will contain scripts and executable files that may need to be excluded from antivirus checks.
The following are examples from a standard Windows system. Changing paths within appsettings.json or within the installer will require changing which directories are execluded.
It may be necessary to exclude certain executables that will run PowerShell scripts. The below is a list of executables that will run PowerShell from PowerShell Universal.
At this point, Universal is up and running. You can navigate to the admin console by visiting http://localhost:5000 by default. The default username is admin with a password of admin.
If you are using Docker Compose v1 please adjust the commands accoridingly. More infromation on Docker Compose can be found .
In order to run PowerShell Universal, you can use the provided container image. The docker image is available on .
You can also download the ZIP from our if you would like to xcopy deploy the files on Windows or Linux.
You can install PowerShell Universal using the . The package runs the MSI install. It will install Universal as a service and open a web browser after the install.
See the .
Please visit the for information on how to configure PowerShell Universal as an IIS website.
| Path | Description |
|---|
| Name | Description |
|---|
%ProgramData%\PowerShellUniversal | Contains log files and appsettings.json |
%ProgramData%\UniversalAutomation | Contains PowerShell scripts and artifacts. Contains the single file database when not using SQL integration. |
%ProgramFiles(x86)\Universal | Contains PowerShell Universal application executables, libraries and modules. |
Universal.Server.exe | The PowerShell Universal core service. |
Universal.Agent.exe | The PowerShell Universal agent environment executable. |
pwsh.exe | PowerShell 7.x |
PowerShell.exe | PowerShell 5.x |
INSTALLFOLDER | The installation folder for PowerShell Universal | %ProgramFiles(x86)%\Universal |
TCPPORT | The TCP port the HTTP server will be listening on. | 5000 |
REPOFOLDER | The repository folder to save the configuration files to. | %ProgramData%\UniversalAutomation\Repository |
CONNECTIONSTRING | The LiteDB or SQL connection string. | %ProgramData%\UniversalAutomation\database.db |
DATABASETYPE | LiteDB or SQL | LiteDB |
STARTSERVICE | Whether to start the service after install (0 or 1) | 1 |
SERVICEACCOUNT | The service account to set for the Windows service | None |
SERVICEACCOUNTPASSWORD | The service account password to set for the Windows Service | None |