# Self-Hosting Packages

> Host your own Package source so everyone in your organization can publish and install internal Packages.

URL: https://www.trakhound.com/docs/trakhound-framework/self-hosting-packages

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`).

Diagram: Engineers publish Packages to your own Package source, an Instance running TrakHound.Packages.Api, protected by API keys. Approved first-party Packages can be copied in from the public source with the Packages App. Test and production Instances list your source on their Sources tab and install from it.

## 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](https://www.trakhound.com/docs/trakhound-framework/services), routed through the API's [Router](https://www.trakhound.com/docs/trakhound-framework/routing):

| 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](https://www.trakhound.com/docs/trakhound-framework/security) so only authorized engineers and Instances can publish or download Packages, for example with an API key per team or an [Identity](https://www.trakhound.com/docs/trakhound-framework/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](https://www.trakhound.com/docs/trakhound-framework/cli)):

```
managementServer: http://packages.mycompany.local:8472
organization: MyCompany
apiToken: ********
```

Or put a [Publish Target](https://www.trakhound.com/docs/trakhound-framework/packages#publish-targets) 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](https://www.trakhound.com/docs/trakhound-framework/packages#package-versions)), 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](https://www.trakhound.com/docs/trakhound-framework/packages#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](https://www.trakhound.com/docs/trakhound-framework/configuration#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](https://www.trakhound.com/docs/trakhound-framework/environments).

## 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. |
