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).
th packages dotnet --publish with an API tokenTrakHound.Packages.Api (ex. http://packages.mycompany.local:8472), protected by security profiles and API keys
Testing organizationProductionWhy 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
TestingandProduction) 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:
| Service | Used for | Example Service Package |
|---|---|---|
| Tables | Package information and metadata (queries use T-SQL) | TrakHound.SqlServer.Service |
| Blobs | Package file contents | TrakHound.FileSystem.Service |
| Key-Values | Cached Package information | TrakHound.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.
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):
| Method | Route | Description |
|---|---|---|
| GET | organizations | List the organizations that have Packages. |
| GET | {organization}/latest | The 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}/versions | Every version of a Package. |
| GET | {organization}/{id}/{version}/download | Download a Package file. |
| POST | {organization} | Upload a Package file (request body is the .thp file). |
| DELETE | {organization}?packageUuid={uuid} | Delete a single Package version. |