This page outlines how to set up and use the Solsta deployment executables in your CI/CD pipeline to manage your deployments. The Solsta deployment executables are used instead of plugins for tools such as TeamCity and Jenkins to upload your builds and make API calls to deploy and promote your releases.
Table of Contents
Prerequisites
The following components are required on all platforms:
.NET 8 runtime or SDK
Solsta console tools – required for deploying releases. See below for download instructions.
Ubuntu 22 Prerequisites
- In order to run the console executables the machine requires GLIBC 2.35.
Extract the executables and give execute permissions to the following files:
direct_get/direct_get
manifest/manifest
release_deploy/release_deploy
manifest_promote/manifest_promote
- cleanup/cleanup
Credentials File
Create a JSON file on your machine with the following contents:
{
"consoleCredentials": {
"clientId": "super",
"clientSecret": "secret",
"grant": "clientCredentials"
}
}
Replace the clientId and clientSecret values with those provided by Solid State Networks. Save the file and note the path to this JSON file, as it will be used in all subsequent arguments. Example:
--console_crednetials=c:/deploy/solsta_auth.json
Solsta Console Tools
Any machine deploying builds will require the Solsta console tools. These tools are used for scanning source files and uploading data during deployments. Use the direct_get executable with arguments below to download the console tools:
version – Version of the Solsta deployment tools.
target_directory – Path on machine where the console tools will be downloaded to. This should be an empty directory. Note that the script will automatically create a “console” folder within the specified directory.
component – Specify a value of
consolehere to avoid downloading a full SDK. Other files in the SDK are not related to Solsta.
Example Run
direct_get.exe --version=7.2.49 --target_directory=C:/ssn/solsta/deploy/7.2.49/ --component=console --console_credentials=c:/ssn/solsta/deploy/solsta_auth.json
Output
Script Execution
Arguments are prepended with double slashes -- and appended with an equals sign =
Example:
--argument1=foo --argument2=bar
When running the scripts, always specify the path to your credentials files using the console_credentials argument. When deploying or promoting, you must also specify the path to the console tools for the console_directory argument. debug_network and log_path arguments are optional, but we recommend using them to track activities and aid with troubleshooting. The deployment executables will automatically enumerate existing log files so that session logs are not overwritten.
You can use the log_json argument to change the script output to JSON. Sample output:
{"level": "INFO", "message": "Output log path set to c:\\ssn\\deployscripts\\3.9\\logs\\productlist.log", "json_data": {}, "timestamp": "2023-10-07 01:17:03", "filename": "config.py"}
{"level": "INFO", "message": "Solid State Networks deployment script version 3.9.1 on Python 3.9.13 (tags/v3.9.13:6de2ca5, May 17 2022, 16:36:42) [MSC v.1929 64 bit (AMD64)]", "json_data": {}, "timestamp": "2023-10-07 01:17:03", "filename": "config.py"}
{"level": "INFO", "message": "Running manifest.exe", "json_data": {}, "timestamp": "2023-10-07 01:17:03", "filename": "config.py"}
{"level": "INFO", "message": "Session ID = d699736f-8254-401e-a808-b73afc635f0a", "json_data": {}, "timestamp": "2023-10-07 01:17:03", "filename": "config.py"}
{"level": "INFO", "message": "DotNet Core version check returned 6.0.13", "json_data": {}, "timestamp": "2023-10-07 01:17:03", "filename": "config.py"}
{"level": "INFO", "message": "Getting product data...", "json_data": {}, "timestamp": "2023-10-07 01:17:03", "filename": "manifest.py"}
{"level": "INFO", "message": "product GET - results found", "json_data": [{"product": "88d692e7-5a15-4469-91fe-6e41d5cf4dde", "org": "org_123abc456def789", "createdTime": 1695818741, "description": "Impossible Missions Force", "modifiedTime": 1696316666, "name": "IMF", "permissions": ["can_delete", "can_update", "can_create_environment", "can_manage_members"]}, {"product": "de4aa537-36d3-4dd3-a365-9eea85c94b58", "org": "org_123abc456def789", "createdTime": 1695690557, "description": "Earth's Mightiest Heroes", "modifiedTime": 1695690557, "name": "The Avengers", "permissions": ["can_delete", "can_update", "can_create_environment", "can_manage_members"]}], "timestamp": "2023-10-07 01:17:04", "filename": "manifest.py"}
Sample Usage
Deploy a release to a named product, environment and repository
This step assumes you have already created a Product, Environment and Repository by using the Create commands in this article, or creating the objects in the Solsta Desktop Application. Missing objects can be created automatically – see the auto-create commands below for an example.
/release_deploy --console_directory=/home/qa/ssn/direct/7.2.49/console/ --process_default=API --console_credentials=/home/qa/ssn/deployscripts/solsta_auth.json --product_name=Pixel --env_name=Buds --repository_name=Pro --source=/home/qa/ssn/source/1.0.0/ --version=1.0.0 --notes_location="https://github.com/pixel/buds/releases/1.0.0" --debug_network --log_path=/home/qa/ssn/deployscripts/3.8.5/logs/deploy.log
Deploy a release with sync and exclude arguments
release_deploy --console_directory=/home/qa/ssn/direct/7.2.49/console/ --process_default=API --console_credentials=/home/qa/ssn/deployscripts/solsta_auth.json --product_name=Pixel --env_name=Buds --repository_name=Pro --source=/home/qa/ssn/source/2.0.0/ --version=2.0.0 --notes_location="https://github.com/pixel/buds/releases/tag/2.0.0" --sync_attributes --sync_timestamps --exclude="bin/mac64/*;bin/lin64/host" --debug_network --log_path=/home/qa/ssn/deployscripts/3.10.0/logs/deploy.log
Deploy a release that auto-creates new environment and repository
The autocreate argument can be used to create Products, Environments and Repositories if they do not already exist. Always use the location and process_default arguments as listed below.
release_deploy --console_directory=/home/qa/ssn/direct/7.2.49/console/ --process_default=API --console_credentials=/home/qa/ssn/deployscripts/solsta_auth.json --autocreate --location --product_name=Cars --env_name=Honda --repository_name=Accord --source=/home/qa/ssn/source/1.0.0/ --version=1.0.0 --notes_location=https://github.com/honda/accord/releases/tag/1.0.0 --debug_network --log_path=/home/qa/ssn/deployscripts/3.10.0/logs/deploy.log
Promote a release between two environments
manifest_promote --console_directory="/home/qa/ssn/direct/7.2.49/console" --console_credentials="/home/qa/ssn/deployscripts/solsta_auth.json" --process_default=API --source_product_name=Pixel --source_env_name=Buds --source_repository_name=Pro --product_name=Pixel --env_name=Phone --repository_name="Gen 1" --debug_network --log_path=/home/qa/ssn/deployscripts/3.10.0/logs/promote.log
Promote a different release within the same environment
manifest_promote --console_directory="/home/qa/ssn/direct/7.2.49/console" --console_credentials="/home/qa/ssn/deployscripts/solsta_auth.json" --process_default=API --product_name=Pixel --env_name=Buds --repository_name=Pro --release_version=2.0.0 --debug_network --log_path=/home/qa/ssn/deployscripts/3.10.0/logs/promote.log
Configure Launch Arguments for Environment
NOTE: Version 1.10 of the Solsta Desktop Application added the ability to configure launch buttons for an environment via its User Interface. This means you can manage launch buttons from both the Solsta Desktop App or via the Deployment Executables. While the Solsta UI automatically reads the latest launch button changes for an environment, the executables DO NOT. That is: if you make a change to an Environment’s launch buttons on the Solsta Desktop Application, that change will NOT be automatically included the next time you run the manifest executable to configure launch arguments. For that reason, you must always include a complete list of the latest Launch Button entries for the selected environment when using the manifest executable to configure launch arguments.
manifest --object=launch --task=set --product_name=Cars --env_name=Honda --launch_name="Start Engine" --launch_executable=vtec.exe --launch_arguments="--1.4 --DOHC" --launch_name="Downshift" --launch_executable="{installDirectory}bin/shift.exe" --launch_arguments="/rpms /increase" --console_credentials="/home/qa/ssn/deployscripts/solsta_auth.json" --debug_network --log_path=/home/qa/ssn/deployscripts/3.10.0/logs/configure_launch.log Examples:
--launch_executable={installDirectory}system/binaries/GameClient.exe
--launch_arguments={installDirectory}subfolder/configuration.ini Create a Product
manifest --object=product --task=create --product_name=Cars --description=Automobiles --console_credentials="/home/qa/ssn/deployscripts/solsta_auth.json"
Create an Environment
Creating environments requires values for the following arguments:
publish_location – Delivery URL used by Solsta client when downloading or updating environments
source_location – Bucket URL for Solsta storage
The location values are visible from creating an environment in the Solsta Desktop Application and then viewing the environment details. Alternatively, you can ask Solsta support for those values.
manifest --object=env --task=create --product_name=Cars --env_name=Toyota --description=Reliable --publish_location=https://dunder.akamaized.net/ --source_location=s3://ssn-dunder/ --console_credentials="/home/qa/ssn/deployscripts/solsta_auth.json"
All the scripts support using unique IDs for objects like Products, Environments and Repositories in the argument strings. Example arguments using IDs:
--product_id=73062b10b866874c8570a06e9fff77eb --env_id=a36fee6ce1976042bd63821fefd954d1 --repository_id=3f0e11a86c811d478b3f0684d0256a2e
The IDs can be retrieved using the manifest executable and GET task (see examples below).
If using the “name” arguments for objects, make sure you have a system in place to avoid duplicates, as they will cause errors. Sample friendly name arguments:
--product_name=Cars --env_name=Toyota --repository_name=Camry
Create a Repository
manifest --object=repository --task=create --product_name=Cars --env_name=Toyota --repository_name=Camry --description=1997 --console_credentials="/home/qa/ssn/deployscripts/solsta_auth.json"
Note: Use the --optional=true argument to create an optional repository. Read more about Optional Repositories.
List Repositories in a Named Product and Environment
manifest --object=repository --task=get --product_name=Pixel --env_name=Buds --console_credentials="/home/qa/ssn/deployscripts/solsta_auth.json"
List Releases in a Named Product, Environment, and Repository
manifest --object=release --task=get --product_name=Pixel --env_name=Buds --repository_name=Pro --console_credentials="/home/qa/ssn/deployscripts/solsta_auth.json"
Delete a Release
Deleting a release requires its release ID. This can be retrieved from the Solsta Desktop Application or the “List releases” command.
If your goal is to delete files that have been deployed to your storage bucket, we recommend deleting releases only, then running the Cleanup script on an existing Product, Environment and Repository. Please read the cleanup section below for more information about how the Cleanup step deletes unused data from storage.
manifest --object=release --task=delete --product_name=Pixel --env_name=Buds --repository_name=Pro --release_id=2b1ce5e82cdb4a4d1b3f54f17a957ab816d3e3280c546777ff289ad5c91ffb21 --console_credentials="/home/qa/ssn/deployscripts/solsta_auth.json"
Cleanup - Storage Deletion
The Cleanup script cleans up (deletes) old, unused release data from the origin bucket(s) associated with the specified Product. Unused pieces are determined by comparing piece files in a Product in a given Location with pieces required by all releases in the Product tree. Depending on the size and volume of the releases you have deployed, this can be a lengthy process as it reads and compares all the data for that product on the storage bucket. We recommend this process to be run only as needed at periodic intervals. Pieces less than 24 hours old will not be deleted to avoid deleting pieces from in-progress deployments.
The cleanup script requires an existing Product, Environment and Repository in order to determine unused pieces for existing releases. For this reason, we recommend you do NOT delete parent objects if your goal is to delete unused data from your storage bucket. Instead, we recommend deleting releases ONLY, then running Cleanup. After the Cleanup completes, then parent objects – Products, Environment and Repositories – can be deleted.
Releases can also be deleted on the Solsta Desktop Application (version 1.9 or later).
cleanup --console_credentials='/home/qa/ssn/deployscripts/solsta_auth.json' --console_directory='/home/jenkins/ssn/direct/7.2.49/console' --product_name=DS_3.10.0 --source_location=s3://ssn-solsta/ --dry_run --debug_network --log_path=/home/jenkins/ssn/deployscripts/3.10.0/logs/cleanup_dry.log
Reference Documentation
Global
Parameters applicable to all executables.
| Parameter | Type/Usage | Description | Default |
|---|---|---|---|
| console_directory | directory path | Path to directory containing console executables | {script_directory}/console/ |
| axis_version | string | Instructs Axis API to use given version of Console Tools; set to null/None to use version from local Console app | 6.0.2 |
| certificate_identity | string | Certificate thumbprint or subject name to search the certificate_store for | null |
| certificate_password | string | Password for cert specified in certificate_path | null |
| certificate_path | file path | Path to certificate used for signing executable files | null |
| certificate_store | string | Name of store containing certificate information | null |
| config_print | boolean | Write all config options to log for debugging | |
| console_config | file path | Path to additional console config JSON file. Same as console app’s –config= parameter. All server/CDN credentials should be placed in this file. | |
| console_credentials | dictionary or file path | JSON object, or path to file containing JSON-formatted credentials for Console apps. See “Login credentials” below. Note that only a file path can be given on the command line. | |
| console_stdin | boolean | Pass all console inputs via stdin for added security. Only supported in DIRECT versions >= 7.0.1.4, 6.2.2, 6.1.2.85. | |
| debug | boolean | Display/log debug information | false |
| debug_network | boolean | Display/log extra debug information when communicating with API. Automatically enables debug. | false |
| string | Optional parameter that will be logged to aid in auditing usage | ||
| ksp_alias | string | Name of the key alias. | null |
| ksp_name | string | Name of the cryptographic key storage provider. | null |
| ksp_pin | string | Smart card pin. | null |
| ksp_pubkey | string | Path to the public certificate for signing key. | null |
| location | boolean | Supplement local CDN credentials with those retrieved from the Location service. Ignored if manifest_api is Null. | true |
| log_json | boolean | Write log output in JSON instead of raw text. | false |
| log_path | file path | Write log output to path in addition to stdout. Will create directory if missing. Will rename existing file. | |
| manifest_api | string | End point to use when using Manifest API. Set to null to disable. | manifest/ |
| pem_path | file path | Path to PEM certificate for JSON signing | null |
| pkcs11_uri | uri string | PKCS#11 URI. | null |
| process_default | string=[API, console] | Location performing certain computing tasks | |
| quiet | boolean | Display/log only errors | false |
| user_info | string | Optional username that will be logged to aid in auditing usage |
manifest
Command-line access to Manifest API. Use object and task. The standard REST tasks (get, post, put, delete) are passed through to the API.
Tasks:
- create, delete, and update pass the complete request through to the API, displaying the response on error
- get passes the information through to the API and displays the response
Exceptions:
- history
- create adds a repository/release pair
- delete can either delete a timestamp or a repository/release pair, depending on if a created_time is present
- launch (uses a “launch object” consisting of launch_name, and optionally launch_executable and launch_arguments)
- add adds the given launch object(s) to the environment’s list
- delete removes the given launch object(s) specified by launch_name from the environment’s list
- get
- retrieve the launch object for a given launch_name
- returns all objects if no name is given.
- set will replace the existing set of launch objects with the set objects given
- update replaces the values for launch_executable and launch_arguments for the given launch object(s)
Note on required parameters: object and task are required. The others may be required; see the “Applies to” and ” Description” columns to determine if they are necessary for a given call.
WARNING: Using this script directly allows the user to violate the “business rules.” Adding/removing data directly ( especially history data) may cause system instability. Other scripts call these functions in a safe manner.
| Parameter | Type/Usage | Applies to | Description | Default |
|---|---|---|---|---|
| object | string: env, history, product, release, repository, update_path, launch | – | Manifest object to perform task on | – |
| task (except launch) | string: create, delete, get, update | all objects except launch | – | |
| task (launch) | string: add, delete, get, set, update | launch object | – | |
| env_id | string | env, history, launch, release, repository, update_path | Environment ID. Can be determined from env_name if required. Not required for create. | Auto-generated GUID for create tasks; looked up from env_name for others |
| env_name | string | env, history, launch, release, repository, update_path, launch | Environment name | – |
| launch_name | string | launch | Name of a launch object for display/organization purposes. May be entered multiple times to specify multiple objects. (required whenever a launch object is specified) | – |
| product_id | string | env, history, launch, product, release, repository, update_path | Product ID. Can be determined from product_name if required. Not required for create. | Auto-generated GUID for create tasks; looked up from product_name for others |
| product_name | string | env, history, launch, product, release, repository, update_path | Product name | – |
| release_id | string | history, release | Release ID | – |
| repository_id | string | history, release, repository | Repository ID. Can be determined from repository_name if required. Not required for create. | – |
| repository_name | string | history, release, repository | Repository name | Auto-generated GUID for create tasks; looked up from repository_name for others |
| alias_location | URI string | env | Alternative uri used by a client when retrieving an asset | empty string |
| catalog_location | URI string | env | Alternative uri used by a client when retrieving an asset | empty string |
| chain_delete | string: true/false | DELETE tasks | Delete all sub-objects before deleting object | True |
| created_time | timestamp | history | Timestamp of object | – |
| description | string | env, product, release, repository | Friendly description for object | empty string |
| dry_run | boolean | DELETE tasks | List items that would have been deleted instead of actually deleting | False |
| force_update | boolean | snapshot | Re-add snapshot even though current repository/release pair hasn’t changed | False |
| launch_arguments | string | launch | All arguments to be passed to launch_executable. May be entered multiple times, once per launch_name | empty string |
| launch_executable | string | launch | Executable to launch for an Environment in Solsta. May be entered multiple times, once per launch_name | empty string |
| limit | integer | GET tasks | Maximum number of items to return | 0 (unlimited) |
| mask | string | update_path | Base-64 encoded bitfield | empty string |
| metafile_location | URI string | env | Alternative uri used by a client when retrieving an asset | empty string |
| notes_location | string | release | Location of release notes | empty string |
| optional | string boolean | repository | If true, the repository is optional. Otherwise, the repository is required. | False |
| publish_location | URI string | env | Alternative uri used by a client when retrieving an asset | empty string |
| search_query | query string | GET tasks | Value to search on. ' and \ must be escaped with \ | empty string |
| sort_direction | string: backward, forward | GET tasks | Direction to perform sort. Forward=start from beginning; backward=start with most-recent | forward |
| sort_field | string | GET tasks | Sort field to use with sort_direction. Case-sensitive. Fields vary with API endpoint; see API documentation. | Depends on endpoint |
| size | integer | release, update_path | Size of data | 0 |
| source | string | update_path | Release to update from | – |
| source_location | URI string | env | Uri used by deploy tools when ingesting assets | empty string |
| source_version | string | update_path | Version string for update path | empty string |
| storage_type | string: pieceshared, piece, file | env | Type of file storage for environment | pieceShared |
| target | string | update_path | Release to update to | – |
| target_version | string | update_path | Version string for update path | empty string |
| update_path_count | integer | env | Number of update paths to create during release/promotion. Set in each environment. | 0 |
| version | string | release | Friendly version string of release | empty string |
manifest_promote
Parameter | Type/Usage | Description | Default |
|---|---|---|---|
env_id | string | Target environment ID; required, but may be derived from env_name |
|
env_name | string | Target environment name |
|
product_id | string | Target product ID; required, but may be derived from product_name |
|
product_name | string | Target product name |
|
release_id | string | SourceID to promote; required, but may be derived from release_version or implied by the current release for the source environment and repository |
|
release_version | string | Version to promote |
|
repository_id | string | Target repository ID; required, but may be derived from repository_name |
|
repository_name | string | Target repository name |
|
source_env_id | string | Source environment ID. May be derived from source_env_name | env_id |
source_env_name | string | Source environment name; if absent, will default to env_name if needed. |
|
source_product_id | string | Source product ID. May be derived from source_product_name | product_id |
source_product_name | string | Source product name | product_name |
source_repository_id | string | Source repository ID. May be derived from source_repository_name | repository_id |
source_repository_name | string | Source repository name | repository_name |
alias_file_write | string boolean | Writes alias file for non-Manifest promotion | False |
env_file_write | string boolean | Write environment file alongside alias file (if alias_file_write is True) | True |
env_dict_write | string boolean | Write environment dictionary file alongside alias file (if alias_file_write is True) | True |
release_deploy
Deploys the contents of a directory to a server.
Parameter | Type/Usage | Description | Example |
|---|---|---|---|
base_url | URL | Base URL for server/CDN. Required, but can be derived from env_id |
|
repository_id | string | Unique repository identifier. Cannot contain dots. Required, but may be derived from repository_name. |
|
source | path | Full (not relative) path to file or directory to be deployed. If directory, source must end in a trailing slash. |
|
sync_directory | directory path | directory (remote or local) containing repositories. Required, but can be derived from env_id |
|
alias_name | string | Alias, if you don’t want to bother using promote.py. Can be given multiple times on the command line, or as a list in a config file. |
|
autocreate | boolean | Automatically create product/env/repository using associated name if name cannot be found in Manifest. False by default. |
|
base_url_metafile | URL | Base URL for metafile (defaults to use base_url) |
|
description | string | Your unique name for this release |
|
env_id | string | Environment ID for Manifest |
|
env_name | string | Environment name for Manifest |
|
exclude | string list (semicolon-delimited) | List of files to exclude. Path is relative to source path. Allows wildcards (*) and wildcard negation (!) |
|
executable_files | relative file path | Relative path (beneath input_directory) of file to be marked as executable in metafile. Can be set multiple times. |
|
gzip | string | Gzip output piece files |
|
hidden_files | relative file path | Relative path (beneath input_directory) of file to be marked as hidden in metafile. Can be set multiple times. |
|
include | string list (semicolon-delimited) | List of files to include; all other files in –source path will be ignored. Path is relative to source path. Allows wildcards (*) and wildcard negation (!) |
|
password | string | Encrypts output with AES256 using given password |
|
product_id | string | Product ID for Manifest |
|
product_name | string | Product name for Manifest |
|
promote | string true/false | Automatically promote release to target env (default=True) |
|
readonly_files | relative file path | Relative path (beneath input_directory) of file to be marked as read-only in metafile. Can be set multiple times. |
|
repository | string | Maps to repository_id for backward compatibility |
|
repository_name | string | Repository name for Manifest |
|
sync_attributes | boolean | If set, metafiles are created with the file attributes recorded |
|
sync_timestamps | boolean | If set, metafiles are created with the file timestamps recorded |
|
version | string | Information about this release such as your internal version number. |
|