Run SAMO 10 backend as local Windows services

This guide describes a single PowerShell script, install-samo-local.ps1, that downloads the SAMO 10 backend services from a Maven repository and installs them as local Windows services (via WinSW). All services run on localhost.

It is intended for a local / standalone deployment where you already have the configuration on disk and only need to pull the binaries and run them as services — without Docker, Nginx or an external orchestrator.

:::info What the script does and does not do Provisions automatically (downloads if missing):

• JDK 17 (Eclipse Temurin, optional auto-download)
• WinSW service wrapper
• The 6 backend service JARs (latest version resolved from Maven)
• The C:\samo directory structure
• One Windows service per backend service, started and set to start automatically

You provide (the script does not download these):

• Metadata packages (samo_packages_root)
• environment.properties and friends (samo_env_configuration) — these also define the database connection, JWT secrets and inter-service URLs
• A reachable database (configured in the properties) :::

Services and contexts

The script installs the following services. The HTTP port comes from your properties files — the script does not set ports. Each service is published under a context path via -Dserver.servlet.context-path.

Service	Maven artifact	Context path
samo-gateway	com.asseco.samo:samo-gateway	/samo
samo-application-server	com.berit.lids:lids-as	/lids
samo-security-manager	com.asseco.samo:samo-security-manager	/security
samo-license-server	com.asseco.samo:samo-license-server	/license
samo-user-service	com.asseco.samo:samo-user-service	/userService
samo-auth-server	com.asseco.samo:samo-auth-server	/authServer

Windows services are named SAMO-LOCAL-<service> (e.g. SAMO-LOCAL-samo-gateway).

Prerequisites

1. Windows 10/11 (or Windows Server) with PowerShell 5.1+.
2. Administrator rights — installing Windows services requires an elevated PowerShell.
3. JDK 17 — either installed already, or let the script download Eclipse Temurin 17 automatically ($AutoDownloadJdk = $true, the default).
4. Configuration on disk:
   • metadata packages folder → passed as -PackagesRoot
   • environment.properties (and any extra .properties) → passed as -EnvConfiguration
   • a data root folder → passed as -DataRoot
5. Access to a Maven repository that hosts the SAMO artifacts → passed as -MavenRepoBase.

Download the script

Download install-samo-local.ps1

Save it to a working folder, e.g. C:\samo-install\.

Parameters

These can be passed on the command line (no need to edit the file):

Parameter	Meaning	Default
-JavaHome	Path to JDK 17. If java.exe is missing here, Temurin 17 is auto-downloaded.	C:\Program Files\Eclipse Adoptium\jdk-17...
-MavenRepoBase	Base URL of the Maven repository hosting the artifacts.	https://packages.samo-asseco.com/repository/maven-releases
-PackagesRoot	-Dsamo_packages_root — metadata packages folder.	C:\samo\configuration
-EnvConfiguration	-Dsamo_env_configuration — properties file(s); join multiple with ;.	C:\samo\environment\environment.properties
-DataRoot	-Dsamo_data_root — data root folder.	C:\samo\data\lids\local
-TeighaLibs	Optional folder with the Teigha/JAI *.jar + *.dll (+ *.txv) files. When set, they go on the app server's classpath + PATH (enable DGN/DWG via lids.dgnv8.* in properties).	(empty — Teigha off)
-SkipDownload	Skip the Maven download step (use already-downloaded JARs).	—
-Uninstall	Stop and remove all SAMO-LOCAL-* services.	—

Other settings (memory, WinSW version, service list, JDWP debug, extra -D properties) live in the SETTINGS block near the top of the script.

Run

Open PowerShell as Administrator, then allow script execution for the current session:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force

Run the script as a single line (passing your own paths):

.\install-samo-local.ps1 -JavaHome "C:\Program Files\Java\jdk-17" -MavenRepoBase "https://<your-maven-repo>" -PackagesRoot "C:/metadata/packages" -EnvConfiguration "C:/metadata/environment.properties;C:/metadata/local.properties" -DataRoot "C:/data"

:::tip Multiple properties files When passing more than one properties file to -EnvConfiguration, separate them with ; and keep the whole value in quotes — otherwise PowerShell treats ; as a command separator. :::

If your environment blocks Set-ExecutionPolicy, launch via a child process that bypasses the policy:

powershell -ExecutionPolicy Bypass -File ".\install-samo-local.ps1" -JavaHome "C:\Program Files\Java\jdk-17" -MavenRepoBase "https://<your-maven-repo>" -PackagesRoot "C:/metadata/packages" -EnvConfiguration "C:/metadata/environment.properties;C:/metadata/local.properties" -DataRoot "C:/data"

DGN/DWG (Teigha) support

If the application server must read DGN/DWG backdrops, pass -TeighaLibs pointing to a folder that contains all Teigha/JAI files — both the *.jar libraries and the native *.dll files (and the *.txv render modules, e.g. WinBitmap.txv):

.\install-samo-local.ps1 -JavaHome "C:\Program Files\Java\jdk-17" -MavenRepoBase "https://<your-maven-repo>" -PackagesRoot "C:/metadata/packages" -EnvConfiguration "C:/metadata/environment.properties" -DataRoot "C:/data" -TeighaLibs "C:/teigha"

When -TeighaLibs is set, the script launches the application server via classpath + JarLauncher (Spring Boot's JarLauncher ignores -Dloader.path) and puts the folder on the classpath and on the service PATH. It does not touch lids.dgnv8.* — enabling DGN/DWG and choosing the render module is configuration and stays in your properties files.

:::note Teigha prerequisites

• The Teigha/JAI files are not downloaded — provide them in the -TeighaLibs folder.
• Enable DGN/DWG in your properties: lids.dgnv8.enabled=true and a headless render module lids.dgnv8.renderingModule=WinBitmap.txv (WinOpenGL.txv needs a real GPU/OpenGL context).
• The Visual C++ 2010 Redistributable must be installed (MSVCP100.dll / MSVCR100.dll).
• Verify it loaded: look for Teigha initialized in the application server log. :::

Verify

# Service status
Get-Service SAMO-LOCAL-*

# Application server log
Get-Content C:\samo\logs\local\samo-application-server\*.out.log -Tail 40

# Health check (replace <port> with the lids HTTP port from your properties)
curl http://localhost:<port>/lids/api/rest/health/

:::note Health 200 ≠ ready The application server returns HTTP 200 on /api/rest/health/ as soon as Tomcat is up, but stays in privileged mode for another ~30–60 s while metadata loads. Wait for state : System started in …\data\lids\…\logs\system.0.log before calling business endpoints. :::

Uninstall

.\install-samo-local.ps1 -Uninstall

Troubleshooting

Symptom	Cause / fix
running scripts is disabled on this system	Run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force, or use the powershell -ExecutionPolicy Bypass -File … form.
Run PowerShell as Administrator	The script must run elevated to install Windows services.
-JavaHome : The term … is not recognized	The command was split across lines. Run it as one physical line, or use backtick (`) continuations carefully in a script file.
Failed to download maven-metadata.xml	-MavenRepoBase is wrong or unreachable, or the repository requires authentication. Verify the exact repository name/URL you were given.
Service starts then stops	Check C:\samo\logs\local\<service>\*.out.log. Most often a database/connectivity issue defined in your properties.
App server stuck "starting"	DB unreachable or wrong credentials (both come from your properties), or metadata still loading.

Notes

• Ports are taken from your properties files; the script never overrides them.
• Database and inter-service URLs are taken from your properties; the script never sets dataSource.*.
• Context paths are set via -Dserver.servlet.context-path and override any value in the properties. To take contexts from properties instead, clear the Context field in the $Services list.
• The script is idempotent — existing downloads and services are reused/recreated on re-run.