Installation

Our docker image is available on Docker Hub. You can start it by pulling and then running with the default port bound.

docker pull ironmansoftware/universal
docker run --name 'PSU' -it -p 5000:5000 ironmansoftware/universal

Tags

Persistent Data

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.

Linux

FROM ironmansoftware/universal:latest
LABEL description="Universal - The ultimate platform for building web-based IT Tools" 

EXPOSE 5000
VOLUME ["/data"]
ENV Data__RepositoryPath ./data/Repository
ENV Data__ConnectionString ./data/database.db
ENV UniversalDashboard__AssetsFolder ./data/UniversalDashboard 
ENV Logging__Path ./data/logs/log.txt
ENTRYPOINT ["./home/Universal/Universal.Server"]

Windows

FROM ironmansoftware/universal:1.3.1-windowsservercore-1809
LABEL description="Universal - The ultimate platform for building web-based IT Tools" 

EXPOSE 5000
VOLUME ["C:/data"]
ENV Data__RepositoryPath C:/data/Repository
ENV Data__ConnectionString C:/data/database.db
ENV UniversalDashboard__AssetsFolder C:/data/UniversalDashboard 
ENV Logging__Path C:/data/logs/log.txt
ENTRYPOINT ["C:/ProgramData/Universal/Universal.Server.exe"]

You can run a build with the build command.

docker build . --tag=universal-persistent

You can start the docker container with the run command and make sure to specify the volume to mount.

docker run --name powershelluniversal --mount source=psudata,target=/data --rm -d  -p 5000:5000/tcp universal-persistent:latest

General

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 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 Persistence

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.

appsettings.json

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.

web.config

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.

Dashboard Components and Frameworks

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.

ZIP Upgrade

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.

MSI Upgrade

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.

IIS Upgrade

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.

LiteDB v5 Upgrade

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.

    "Data": {
    "RepositoryPath": "%ProgramData%\\UniversalAutomation\\Repository",
    "ConnectionString": "filename=%ProgramData%\\UniversalAutomation\\database.db;upgrade=true",
    "DatabaseType": "LiteDBv5",

PowerShell Universal is licensed per server. We provide licenses for individuals and organizations.

You can purchase a license on our website.

What's a server?

A server is a single running instance of PowerShell Universal.

Free Use Restrictions

Universal can be used forever for free with the following limitations.

Universal API

• No authentication

• No Rate Limiting

Universal Automation

• 25 jobs per day

• 2 concurrent jobs

• No Triggers

Universal Dashboard

• No authentication

• No access to diagnostic tools

Downloads

Download the latest version of PowerShell Universal.

Blog

The Ironman Software blog has articles about PowerShell Universal.

Forums

Connect with the PowerShell Universal community.

Discord

Chat with other PowerShell Universal users.

Purchasing

Purchase a license for the features of PowerShell Universal.

Issue Tracker

File a bug report or feature request for PowerShell Universal.

Samples

Samples that can be inserted into your PowerShell Universal system using the PowerShell Universal extension for Visual Studio Code.

Videos

Check out video tutorials for PowerShell Universal.

Getting Started

PowerShell Module

You can use the PowerShell Universal PowerShell module to install the Universal server. To install the module, use Install-Module.

Install-Module Universal

To install the Universal server, you can use Install-PSUServer.

Install-PSUServer -LatestVersion

You can configure the path that the server is stored in by using the -Path parameter.

Install-PSUServer -Path (Join-Path $Env:AppData "PSU")

You can add the PSU server to the PATH environment variable by use the -AddToPath parameter.

Install-PSUServer -AddToPath

Once the server has been installed, you can use Start-PSUServer to start it.

Start-PSUServer -Port 8080

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.

Start-PSUServer -Port 8080 -ExecutablePath (Join-Path $MyPath "Universal.Server.exe")

Chocolatey Package (Windows)

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.

choco install powershelluniversal

Winget (Windows)

You can install PowerShell Universal using Winget. It will run the MSI and install as a service.

winget install ironmansoftware.powershelluniversal

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.

winget install ironmansoftware.powershelluniversal --silent

ZIP Install

You can also download the ZIP from our Downloads page if you would like to xcopy deploy the files on Windows or Linux.

Windows

You can start Universal by unzipping the contents, unblocking the files and then executing Universal.Server.exe.

Expand-Archive -Path .\Universal.zip -DestinationPath .\Universal
Get-ChildItem .\Universal -Recurse | Unblock-File
Start-Process .\Universal\Universal.Server.exe

Linux

On Linux, start the process Universal.Server. You may need to chmod +x the file if it does not start.

Docker

See the Docker page.

MSI Install (Windows)

The MSI install will create a PowerShell Universal service and open the admin console after installation.

Properties

SUPPRESSBROWSER

Setting the SUPPRESBROWSER MSI property to true will prevent the browser from opening after installation.

Next Steps

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!

Install PowerShell Universal

You'll need to install the PowerShell Universal server. There are a lot of ways to do so but you can use the command line below to get started quickly.

choco install powershelluniversal

Install-Module Universal
Install-PSUServer -AddToPath
Start-PSUServer -Port 5000

Install-Module Universal
Install-PSUServer -AddToPath
Start-PSUServer -Port 5000

Open PowerShell Universal

By default, PowerShell Universal is running on port 5000 of localhost. You can access the admin console with the user name admin and any password.

PowerShell Universal Visual Studio Code Extension

We recommend installing the PowerShell Universal Visual Studio Code Extension to provide the best possible editing experience.

You can connect to your instance of PowerShell Universal, browse and insert samples and get up and running right away.

Install the Extension

Install the extension by searching for it in the extension page and clicking Install.

Connect to PowerShell Universal

Click the PowerShell Universal icon on the left hand side and the extension will attempt to connect using the default URL and user name. The extension will notify you once it has connected.

Inserting a Sample

Samples are available via the sample browser. You can select a sample and insert it into your PowerShell Universal instance. You'll need to save the file that is opened by Visual Studio Code for the sample to be inserted.

Learn more about the various features of PowerShell Universal

• APIs

• Automation

• Dashboards

Windows

• or greater or PowerShell v7.0 or greater

• (only for Windows PowerShell)

Linux

• PowerShell v7.0 or great

• Validated Distributions: Ubuntu 18.04

Mac OS X

Universal uses a variety of modern web frameworks and can have issues with older browsers such as Internet Explorer.

The current version of the following web browsers are supported: , , , and

PowerShell Universal can be managed with the PowerShell Universal Visual Studio Code extension. It allows you to connect to a local Universal instance and manage APIs, dashboards and scripts.

Installation

You can download the extension from the . You can also download the extension from within the Visual Studio Code extension pane. Search for PowerShell Universal and click Install.

Configuration

The extension will prompt you for the URL and App Token used to connect to your PowerShell Universal instance. Follow the instructions within the extension when it starts up.

Features

The PowerShell Universal extension adds a new activity pane panel for PowerShell Universal. It has the following sections.

APIs

You can manage APIs with the extension. You will see a list of APIs. You can click the Open endpoints.ps1 button to view the endpoints file and add new endpoints. Clicking the refresh button will reload any endpoints you add. You can click the Insert Invoke-RestMethod to Console to add a call to the endpoint to the PowerShell Integrated Console.

Dashboards

You can manage dashboards with the extension. You will see a list of dashboards underneath this section. You can open the dashboards.ps1 script, open the a single dashboard's script, restart a dashboard and view dashboards. When you open a dashboard script, the dashboard modules will automatically be loaded so that IntelliSense works in VS Code.

Debug Dashboard Process

You can connect the Visual Studio debugger to the dashboard process by right clicking on the dashboard and click Debug Dashboard Process. This requires the PowerShell extension for Visual Studio Code.

After connecting the debugger, you can run commands such as Get-Runspace and Debug-Runspace to begin debugging aspects of your dashboard.

View Dashboard Logs

You can view dashboard logs by right clicking on the dashboard and clicking View Logs. They will open in a new tab.

Scripts

You can manage scripts with the extension. You will see a list of available scripts underneath this section. You can edit the scripts.ps1, edit an individual script and run scripts. When running scripts, you will receive feedback about the status of the script. Scripts with parameters are not supported in VS Code. You can still run them in PowerShell Universal.

Sample Browser

The sample browser can be used to insert samples from the PowerShell Universal Sample Repository into your PowerShell Universal instance. Just save the files it updates and your PowerShell Universal system will reflect the changes.