TrakHound Docs TrakHound Framework Self-Hosting Packages

Self-Hosting Packages

Host your own Package source so everyone in your organization can publish and install internal Packages.
Framework Docs Menu

By default, Instances and the CLI use the public TrakHound Package source (https://www.trakhound.com/management, organization Public). Organizations can also host their own Package source on one of their Instances using the TrakHound.Packages.Api Package. Engineers publish internal Packages to it, and every Instance in the organization can browse and install them from the admin UI or the CLI.

Any server running the Packages API is a package server, and a package source is a package server plus an Organization on it. Its base URL is the server's address without the API's packages route (ex. http://packages.mycompany.local:8472).

Engineersth packages dotnet --publish with an API token
Public sourceCopy approved first-party versions in with the Packages App
publish / copy
Your Package Source An Instance running TrakHound.Packages.Api (ex. http://packages.mycompany.local:8472), protected by security profiles and API keys
TestingProduction
install
Test InstancesInstall from the Testing organization
Production InstancesOnly see approved versions in Production
One catalog of internal Packages for every team, without depending on the internet.

Why Self-Host Packages

  • Internal Packages stay internal - Modules built for your processes are never published outside your network
  • One catalog for every team - Engineers from every department and site publish to and install from the same place, so modules can be shared and reused
  • Approved versions - Control which Packages and versions are available to your Instances, including copies of the first-party Packages you use
  • Isolated networks - Instances install and update Packages from a server on your own network, with no internet connection required
  • Separate stages - Use separate organizations (for example Testing and Production) to control when a Package is made available to production Instances

1. Configure Services on the Hosting Instance

Choose an Instance that the other Instances and engineers can reach, for example a central server on your network. TrakHound.Packages.Api stores Packages using the following Services, routed through the API's Router:

ServiceUsed forExample Service Package
TablesPackage information and metadata (queries use T-SQL)TrakHound.SqlServer.Service
BlobsPackage file contentsTrakHound.FileSystem.Service
Key-ValuesCached Package informationTrakHound.Memory.Service or TrakHound.Redis.Service

The tables are created automatically when the API starts.

2. Install the Packages API

Install TrakHound.Packages.Api on the hosting Instance and create an API configuration for it in the admin UI. Its default route is packages, so the source's base URL is the Instance's URL and the API is available at {baseUrl}/packages:

th packages install TrakHound.Packages.Api

Secure the API with security profiles so only authorized engineers and Instances can publish or download Packages, for example with an API key per team or an Identity provider such as TrakHound.Token.Identity. Sources and the CLI send their configured access token with each request.

3. Publish Packages to Your Source

Set your source as the default in the CLI's cli.config.yaml (see CLI):

managementServer: http://packages.mycompany.local:8472
organization: MyCompany
apiToken: ********

Or put a Publish Target once in a trakhound.package.publish.json file in a parent folder of your Package projects (for example the root of a repository). The CLI uses the nearest one, so every Package below it publishes to your source:

{
  "defaultTarget": "internal",
  "targets": {
    "internal": {
      "destinations": [ { "managementServer": "http://packages.mycompany.local:8472", "organization": "MyCompany" } ]
    }
  }
}

Versions come from git (see Versions from Git), so engineers on different computers build the same version from the same commit, and a version that's already on your source is never replaced.

Then build and publish as usual, or upload an existing Package file:

th packages dotnet --publish
th packages push MyCompany.Machines.Api.thp --server http://packages.mycompany.local:8472 --organization MyCompany

Copy Packages Between Sources

The TrakHound.Packages.App Package (default route trakhound/packages/app) uploads, downloads, and copies Packages between package servers, such as the public source and an Instance running the Packages API. Use it to copy the first-party Packages and versions you have approved from the public source into your own source, or to promote Packages from one organization to another.

IT tools can see who signed a Package without downloading it: GET /packages/{organization}/{id}/{version}/manifest returns a version's manifest and signature, and POST /packages/{organization}/manifests returns them for up to 200 Package UUIDs. The server doesn't check them, so check them with your own list of trusted keys (see Signing and Verification).

4. Add the Source to Your Instances

On each Instance, open the Sources tab of the Packages page in the admin UI and add your source with its base URL, organization, and access token. Engineers can then pick the source on the Browse tab to install and update its Packages. Sources are saved to remotes.config.yaml in the Instance's configuration profile directory:

remotes:
- id: mycompany
  name: My Company
  baseUrl: http://packages.mycompany.local:8472
  organization: MyCompany
  accessTokenName: instances
  accessTokenCode: ********
- id: public
  name: Public
  baseUrl: https://www.trakhound.com/management
  organization: Public

Remove the public source on Instances that should only install approved Packages. To install from your source with the CLI, pass it with --server and --organization:

th packages install MyCompany.Machines.Api --server http://packages.mycompany.local:8472 --organization MyCompany

Or set managementServer and organization in the CLI's cli.config.yaml so th packages install uses your source by default. Deployments aren't downloaded from a package server: they're installed from .thd files (see Deployments).

Organizations

A single source can hold Packages for several organizations. Each organization has its own set of Packages and versions, so you can use organizations to separate sites, departments, or stages. For example, publish to Testing first, and copy the same Package to Production with the Packages App once it has been approved. See Development, Test & Production.

Packages API Reference

Routes are relative to the API's route (default packages):

MethodRouteDescription
GETorganizationsList the organizations that have Packages.
GET{organization}/latestThe latest version of every Package. The optional q parameter filters by Package ID prefix.
GET{organization}/category/{category}The latest version of every Package in a category.
GET{organization}/{id}/versionsEvery version of a Package.
GET{organization}/{id}/{version}/downloadDownload a Package file.
POST{organization}Upload a Package file (request body is the .thp file).
DELETE{organization}?packageUuid={uuid}Delete a single Package version.