Changes to shop floor software should be tried before they reach production. With TrakHound, each environment is its own Instance, and the same versioned Package moves from development to test to production. Process engineers, quality engineers, supervisors, and operators can use new versions in a test environment with test data, and only approved versions are installed in production.
Typical Environments
| Environment | Used by | Typical setup |
|---|---|---|
| Development | Engineers building modules | A local Instance on the engineer's computer. Modules are debugged with dotnet run using sample data in Memory or File System Services. |
| Test | Process engineers, quality, supervisors, and operators | An Instance on a test server with test data or a copy of production data. Runs the version being considered for release. |
| Production | The shop floor | Instances on production servers that only run approved Packages and versions. |
Why Test This Way
- The people who know the process validate it - Process engineers and operators confirm a change works for their process before it affects production
- What was tested is what runs - The same Package file is installed in test and production, so there is no rebuild between approval and release
- No code changes between environments - Modules do not contain connection details, so each environment points at its own data through its own Service configurations
- Easy to roll back - Every Package is versioned, so a previous version can be reinstalled if a problem is found
1. Run an Instance for Each Environment
Run a separate Instance for test and for production, normally on separate servers. On a single installation, configuration profiles keep separate sets of configuration (see Instances):
TrakHound.Instance test
2. Point Each Environment at Its Own Data
Create Service configurations on each Instance for that environment's databases and message brokers, usually set by IT, and add them to the Instance's
Routers. Because modules only call Client.Services, the same Package reads test data on the test Instance
and production data on the production Instance without any changes. See Services.
To try a module on a shared Instance instead, add it to a Zone whose Service Router points at test data. Every Service call the module makes goes to that Router, whatever Router it asks for.
3. Install the Version Being Tested
Publish the new version, then install it on the test Instance:
th packages dotnet --publish
th packages install MyCompany.Machines.App --version 1.4.0
4. Have Process Engineers Test It
Testers use the Apps and APIs on the test Instance the same way they will in production. The admin UI helps them check the results:
- Explorer - Run Functions, call API endpoints, preview App pages, and look at the data in Tables, Key-Values, Blobs, and Messages
- Diagnostics - Review logs, API requests, and App connections to find the cause of a problem
- Workers - Confirm background processes are running and check their CPU usage
Use Identity modules and security profiles so testers can use the Apps without being able to change the Instance's configuration. When a tester finds a problem, fix it, publish a new version, and install it on the test Instance again.
5. Promote to Production
Once the version is approved, install the same version on the production Instance:
th packages install MyCompany.Machines.App --version 1.4.0
To move a whole set of Packages and configuration at once, create a Deployment from the test Instance and install it on production with the admin UI or the CLI. A Deployment can include only some configuration categories (for example Apis and Functions, but not Services), so environment specific settings such as Service connection details stay as they are on production. Put values that differ between environments in Configuration Variables, and review them after installing a Deployment on a new Instance.
To set up a new Instance (for example another site) from the same Deployment, select it on the installer's Deployment page or copy it to the Instance's
deployments folder, and the Instance installs it when it starts.
Copy Jobs and Scheduled Tasks from test to production with Export and Import on the Schedule Board. Imports are checked with a dry run first.
# On the test Instance's root directory
th deployments create machines --version 1.4.0 --output ./deployments
# On the production Instance
th deployments install <deployment-file>.thd
With a self-hosted Package source, use separate organizations such as Testing and Production,
and copy a Package to Production once it has been approved so production Instances only see approved versions.
6. Roll Back if Needed
If a problem is found in production, reinstall the previous version:
th packages install MyCompany.Machines.App --version 1.3.2