Skip to main content

SAMO 10 Service Deployment

Overview​

This guide provides step-by-step instructions for deploying SAMO 10 platform components as Windows Services. The deployment uses a single batch script that automatically installs ALL SAMO backend component JAR files found in a directory as Windows Services using WinSW (Windows Service Wrapper).

By following this guide, you will:

  • Set up the required directory structure
  • Configure all necessary environment variables
  • Install and start all SAMO backend services automatically
  • Verify the installation is working correctly

Prerequisites​

Before starting the deployment, ensure you have the following:

1. Software Requirements​

  • Java Development Kit (JDK): Version 17
    • Example location: C:\Program Files\Java\jdk-17
    • Verify installation: Open Command Prompt and run java -version you should see Java 17 listed

2. Database & Elasticsearch​

  • Configured Database: Oracle or PostgreSQL must be installed and configured
  • Database credentials: You'll need the database password for configuration
  • Elasticsearch 8: Installed and running, configured for SAMO

3. Required Files​

  • WinSW-x64.exe: Windows Service Wrapper executable

  • SAMO Component JAR Files: All backend component JAR files

    • Example files:
      • samo-security-manager-10.0.0.jar
      • samo-license-server-10.0.0.jar
      • samo-user-service-10.0.0.jar
      • samo-gateway-10.0.0.jar
      • (and other components as needed)

  • Installation Script: install-all-samo-services.bat

info

Contact the SAMO support team to obtain the installation script.

4. System Requirements​

  • Administrator Access: Required to install Windows Services
  • Available Ports: Ensure required ports are not in use by other applications
  • Disk Space: Sufficient space for logs and data directories

5. Credentials and Secrets​

Prepare the following credentials (you'll need these during installation):

  • Microsoft IDM Client Secret
  • Database password
  • Any other service-specific credentials/secrets

Deployment Steps​

Step 1: Create Directory Structure​

Create the following directory structure on your system:

C:\samo\
├── configuration\          (Configuration packages root)
├── environment\           (Environment properties files)
│   ├── environment1\
│   └── environment2\
├── data\                  (Persistent data, certificates)
└── logs\                  (Service logs)

C:\deploy\samo-backend\    (Deployment directory)
├── install-all-samo-services.bat
├── WinSW-x64.exe
├── samo-security-manager-10.0.0.jar
├── samo-license-server-10.0.0.jar
├── samo-user-service-10.0.0.jar
└── (other component JAR files)

Step 3: Place Required Files​

  1. Copy JAR files to C:\deploy\samo-backend\

    • All SAMO component JAR files must be in this directory

  2. Copy WinSW-x64.exe to C:\deploy\samo-backend\

  3. Copy install-all-samo-services.bat to C:\deploy\samo-backend\

Your deployment directory should look like:

C:\deploy\samo-backend\
├── install-all-samo-services.bat
├── WinSW-x64.exe
├── samo-security-manager-10.0.0.jar
├── samo-license-server-10.0.0.jar
└── ... (other JARs)

Step 4: Configure the Installation Script​

The installation script accepts the following required parameters:

ParameterDescriptionExample
1. PACKAGES_ROOTRoot of configuration packagesC:\samo\configuration
2. ENV_PROPERTIESSemicolon-separated environment properties filesC:\samo\environment\environment.properties;C:\samo\environment\environment2.properties
3. DATA_ROOTData root directoryC:\samo\data
4. MICROSOFTIDM_SECRETMicrosoft IDM Client Secretyour_secret_here
5. DB_PASSWORDDatabase passwordyour_db_password
6. SERVICE_PREFIXPrefix for service namessamo-10-
7. JAVA_HOME (optional)JDK installation pathC:\Program Files\Java\jdk-17
8. LOG_DIR (optional)Log directoryC:\samo\logs

Step 5: Run the Installation​

  1. Open Command Prompt as Administrator

    • Press Windows + X
    • Select "Command Prompt (Admin)" or "Windows PowerShell (Admin)"

  2. Navigate to the deployment directory:

cd C:\deploy\samo-backend
  1. Run the installation script with your configuration:

Basic installation (using default Java and log paths):

install-all-samo-services.bat C:\samo\configuration "C:\samo\environment\environment.properties;C:\samo\environment\environment2.properties" C:\samo\data YOUR_SECRET_HERE YOUR_DB_PASSWORD samo-10-

Full installation (specifying all parameters):

install-all-samo-services.bat C:\samo\configuration "C:\samo\environment\environment.properties;C:\samo\environment\environment2.properties" C:\samo\data YOUR_SECRET_HERE YOUR_DB_PASSWORD samo-10- "C:\Program Files\Java\jdk-17" C:\samo\logs
warning
  • Replace YOUR_SECRET_HERE with your actual Microsoft IDM Client Secret
  • Replace YOUR_DB_PASSWORD with your actual database password
  • Use quotes around paths that contain spaces
  • Never commit credentials to version control
  1. Monitor the installation:
    • The script will display progress messages for each component
    • Watch for any [ERROR] messages
    • Installation is complete when you see success messages for all components

Step 6: Verify Installation​

After the script completes, verify that services are installed and running:

  1. Check all SAMO services:
sc query state= all | find /i "samo-10-"
  1. Check individual services:
sc query samo-10-samo-security-manager
sc query samo-10-samo-license-server
sc query samo-10-samo-user-service

  1. Check service status in Windows Services Manager:

    • Press Windows + R
    • Type services.msc and press Enter
    • Look for services starting with your prefix (e.g., samo-10-)
    • Verify they are in "Running" state

  2. Check service logs:

    • Navigate to C:\samo\logs\
    • Each component should have its own subdirectory
    • Check for any error messages in the log files

Step 7: Testing Individual Components (Optional)​

If you want to test a single component before installing it as a service:

cd C:\deploy\samo-backend

"C:\Program Files\Java\jdk-17\bin\java.exe" -Xmx1024m ^
  -Dsamo_packages_root="C:\samo\configuration" ^
  -Dsamo_env_configuration="C:\samo\environment\environment.properties;C:\samo\environment\environment2.properties" ^
  -Dsamo_data_root="C:\samo\data" ^
  -DdataSource.password="YOUR_DB_PASSWORD" ^
  -jar samo-security-manager-10.0.0.jar
  • Press Ctrl+C to stop the test run
  • Check output for any errors before proceeding with service installation

What the Script Does​

The installation script performs the following actions automatically:

  1. Validates Prerequisites:

    • Checks that WinSW-x64.exe is present
    • Ensures the log directory exists
    • Verifies that JAR files are available

  2. For Each JAR File:

    • Creates a subfolder for the component
    • Copies WinSW executable (renamed to match the component)
    • Generates a WinSW XML configuration file
    • Stops and removes existing service (if present)
    • Installs the new service
    • Starts the service

  3. Configures Logging:

    • Sets up rolling log files for each component
    • Creates separate log directories per component

Updating Services​

To apply new JAR versions: replace JAR files in the directory and rerun the script. Existing services will be stopped, deleted, and recreated automatically.

tip

Always back up your configuration before updating services. The script will automatically handle service restart, but configuration files should be preserved.

Troubleshooting​

Common Issues and Solutions​

IssuePossible CauseSolution
[ERROR] WinSW not foundMissing WinSW executableEnsure WinSW-x64.exe is in the deployment directory
[ERROR] No JAR files foundJARs not in correct locationPlace all JAR files in the same directory as the script
Service fails to startConfiguration errorCheck component logs in C:\samo\logs\[component-name]\
Port already in usePort conflict with another applicationChange port in configuration or stop conflicting service
Java not foundIncorrect JAVA_HOME pathVerify JDK installation path and update parameter
Access deniedInsufficient permissionsRun Command Prompt as Administrator
Database connection failedWrong credentials or database not accessibleVerify database password and connectivity

Checking Service Logs​

  1. Navigate to the log directory: C:\samo\logs\
  2. Open the subdirectory for the problematic component
  3. Open the latest log file
  4. Look for ERROR or WARN messages
  5. Address any configuration issues found

Manual Service Management​

Use the Windows Services Manager (services.msc) to manually start, stop, or restart services if needed.

Customization​

Adjusting Memory Settings​

To change the memory allocation for services:

  1. Edit the generated XML file in C:\deploy\samo-backend\[component-folder]\
  2. Modify the -Xmx parameter in the <arguments> section
  3. Restart the service

Example: Change from -Xmx1024m to -Xmx2048m

Adding Additional Java Arguments​

To add custom Java properties:

  1. Edit the XML configuration file for the component
  2. Add properties in the <arguments> section
  3. Example: -DHTTPS_ENABLED=true -DHTTPS_PORT=8443
  4. Restart the service

Security Best Practices​

  1. Protect Credentials:

    • Never commit secrets to version control
    • Store credentials securely
    • Use environment-specific configuration files

  2. Restrict Directory Access:

    • Set appropriate ACLs on C:\samo\ directories
    • Limit access to Administrators only:
    icacls C:\samo /grant Administrators:F /t
    icacls C:\samo /remove Users /t

  3. Regular Updates:

    • Keep Java runtime updated
    • Apply SAMO component updates promptly
    • Review security advisories

  4. Monitor Logs:

    • Regularly check service logs for errors or security issues
    • Implement log rotation to manage disk space
    • Consider centralized logging for production environments

Post-Deployment Checklist​

After completing the deployment, verify the following:

  • All services are installed and running
  • Service logs show no critical errors
  • Database connections are successful
  • Application endpoints are accessible
  • Configuration files are properly secured
  • Firewall rules allow necessary traffic
  • Backup procedures are in place
  • Monitoring is configured (if applicable)

Next Steps​

After successful deployment:

  1. Configure application-specific settings
  2. Set up user accounts and permissions
  3. Configure SSL/TLS certificates (if required)
  4. Perform integration testing
  5. Document any environment-specific customizations

Need Help? If you encounter issues not covered in this guide, consult the SAMO support team or refer to the detailed documentation in other sections.