StackRegent install script parameters and unattended installs

Two scripts, one install#

StackRegent is installed by two PowerShell scripts that work together:

Most people only ever run the one-liner. Run install.ps1 yourself when you need options the install script does not pass on, such as other panel ports or another installation folder.

The one-line installer#

Open PowerShell with Run as administrator on Windows Server 2016, 2019, 2022 or 2025 and run:

[Net.ServicePointManager]::SecurityProtocol='Tls12'; & ([scriptblock]::Create((New-Object Net.WebClient).DownloadString('https://panel.stackregent.com/get/stackregent.ps1'))) -LicenseKey SR-XXXXX-XXXXX-XXXXX-XXXXX

The first part makes Windows PowerShell 5.1 use TLS 1.2. The rest downloads the script into memory and runs it with your license key. Add any of the parameters below after the key, for example:

... -LicenseKey SR-XXXXX-XXXXX-XXXXX-XXXXX -AdminEmail ops@example.com -Hostname panel.example.com -Components none

No license yet? The free trial runs for 10 days with 3 hosting accounts and needs no card; it gives you a key in the same format.

Install script parameters#

What the install script does, in order#

1. Checks that PowerShell runs as administrator (skipped with -DownloadOnly).
2. Reads this server's Windows machine ID and derives the fingerprint the panel uses for licensing.
3. Activates the license for this server with the license server. If the license is not active, it stops with the license server's message. Activation binds the license to this machine, so run it on the server you mean to use.
4. Asks the license server for the newest stable release offered to the license, and checks that the version, the download address (it must be on the license server), the size (at most 1 GB) and the SHA-256 are well formed.
5. Downloads the package without following redirects and checks its size, its SHA-256 and its ECDSA signature against the StackRegent release key printed in the script. See release signatures.
6. Unpacks the package into a new temporary folder, refusing any entry whose path would leave that folder, and checks that it contains install.ps1.
7. Runs install.ps1 with -LicenseKey, -Components and, if given, -AdminEmail and -Hostname.

Nothing is installed when any check fails.

install.ps1 parameters#

Run install.ps1 from the unpacked package folder in an elevated PowerShell:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -LicenseKey SR-XXXXX-XXXXX-XXXXX-XXXXX -AdminEmail ops@example.com

-HttpsPort, -HttpPort, -DbPort, -InstallDir, -MariaDBSeries and -MariaDBZip are available only when you run install.ps1 yourself. To change the panel ports after installing, use stackregent panel-port; see command line.

Component IDs#

recommended sets up these components, in this order:

Other IDs you can list: vcredist (Visual C++ 2015-2022 runtime), aspnetcore (ASP.NET Core Hosting Bundle), nodejs, iisnode, git (Git for Windows), composer, wpcli, mssql (SQL Server Express), spamassassin, modsecurity (ModSecurity for IIS with the OWASP Core Rule Set). Components are installed one by one, in the order you give, through the panel's task service, and each prints a result line. A component that fails does not stop the others; install or retry it later under Tools & Settings › Server Components, where you can also add more versions of PHP, Node.js and ASP.NET Core. The full list is on the components page.

What a fresh install sets up#

A fresh install runs eight steps:

1. Installs the IIS role with the features StackRegent hosts websites with, and adjusts the page file, IIS compression and Windows hardening settings.
2. Sets up the panel database, installing the Visual C++ runtime if it is missing.
3. Copies the StackRegent files.
4. Configures the panel and creates the admin account.
5. Registers and starts the services StackRegent, StackRegentTask and StackRegentGuard, and sets the license key.
6. Opens Windows Firewall for the panel ports, websites (80, 443) and website preview (9444).
7. Installs the StackRegent Service Monitor tray app for administrators (skipped on Server Core).
8. Waits for the panel to answer, then sets up the components.

At the end it prints the panel address (https://SERVER-IP:9443/), the login admin and its password. The password is not written to any file. Your browser warns about the self-signed certificate until you install a trusted one.

Upgrades#

Run the install script or install.ps1 again on an installed server and it upgrades in place: it checks IIS, stops the panel services, copies the new binaries, updates the panel database schema, starts the services and sets the license key if you gave one. The admin password and all settings stay as they are. Updates from Tools & Settings › Updates run the same install.ps1 from a verified package; see updating.

Unattended installs#

The install script and install.ps1 ask only for a missing license key, so always pass -LicenseKey when nobody is at the console. A typical unattended install from a provisioning system:

$ErrorActionPreference = 'Stop'
[Net.ServicePointManager]::SecurityProtocol = 'Tls12'
$get = (New-Object Net.WebClient).DownloadString('https://panel.stackregent.com/get/stackregent.ps1')
try {
    & ([scriptblock]::Create($get)) -LicenseKey $env:SR_LICENSE -AdminEmail 'ops@example.com' -Hostname 'panel.example.com' -Components 'recommended'
} catch {
    Write-Error "StackRegent install failed: $_"
    exit 1
}
# set a password your automation captures, instead of reading the console output
& 'C:\Program Files\StackRegent\bin\stackregent.exe' admin-password

stackregent admin-password prints a new random password for admin, which your provisioning system can capture and store in its vault.

Unattended install with other ports or folder#

Download and verify the release first, then run install.ps1 with the options you need:

& ([scriptblock]::Create($get)) -LicenseKey $env:SR_LICENSE -DownloadOnly
# prints: StackRegent <version> is checked and unpacked in <folder>
$dir = Get-ChildItem "$env:TEMP\stackregent-get-*\StackRegent-*" -Directory | Sort-Object LastWriteTime | Select-Object -Last 1
powershell -NoProfile -ExecutionPolicy Bypass -File (Join-Path $dir.FullName 'install.ps1') `
    -LicenseKey $env:SR_LICENSE -HttpsPort 8443 -HttpPort 8080 -AdminEmail 'ops@example.com' -Components 'urlrewrite,php,mariadb-hosting'
if ($LASTEXITCODE -ne 0) { throw "install.ps1 failed with exit code $LASTEXITCODE" }

-DownloadOnly still activates the license for the server, because the license server offers releases only to an active license.

Exit codes and errors#

Common reasons the install script stops:

• run PowerShell as Administrator: open PowerShell with Run as administrator.
• the licence is not usable here: ...: the license is suspended, expired or bound to another server; reissue or renew it in the client area.
• the licence server could not be reached: check outbound HTTPS, DNS and the server clock.
• the release is not signed with StackRegent's release key; nothing was installed: the download was altered or damaged on the way. Try again, and write to support@stackregent.com if it repeats.

And install.ps1:

• StackRegent needs Windows Server 2016 or later: Windows builds older than 14393 are refused. On a desktop edition the script warns but continues.
• Could not find a MariaDB ... Windows zip: download the MariaDB zip yourself and pass -MariaDBZip.
• Database migration failed. or Panel setup failed: ...: read the install log.

Logs#

install.ps1 writes a transcript to <InstallDir>\var\log\install-YYYYMMDD-HHMMSS.log, by default under C:\Program Files\StackRegent\var\log. The license key is replaced by SR-***** in the log, and the admin password is never written to it. The panel's own logs (web.log, task.log) are in the same folder. Updates installed from the panel write install-VERSION.log in the update folder of the installation.