UsageGuard Deployment Guide

Table of Content

• Core Components
  • UsageGuard APIs
  • UsageGuard App
• Dependencies
  • OpenSearch
  • PostgreSQL

Version: 3.2.2 (or later)

This installation guide outline the different requirments and optional features for UsageGuard and how to configure them.

Files required for the walkthrough:

• trace_log_mapping.json
• session_log_mapping.json
• update_db_3.2.2.sql (upgrade from 3.1.0)
• appsettings.json

Required files will be part of deployment package, contact support for any clarification

Core Components

UsageGuard APIs

Request your token and use it to pull UsageGuard docker images.

Tokens are valid for 12 hours, if your token expired please request new one.

./pull_container.sh "<your-token>" "ug-ecr-reverse-proxy"
./pull_container.sh "<your-token>" "ug-ecr-reverse-proxy-app"

Once images are pulled, you need to provide few settings, there are two ways:

Settings File

Override ug-ecr-reverse-proxy (Image for UG API) default settings with your custom appsettings.json by using Bind Mount, Docker Compose or you can use Config Map or Persistant Volume if you are using Kubernetes.

Environment Variables

For example you can set the environment variable Auth__SecretKey instead of setting SecretKey value in Auth section

UsageGuard API

docker run -d --name ug-prod-api \
 -e ASPNETCORE_ENVIRONMENT=Production \
 -e App__LicenseKey=your_license_key \
 -e Auth__SecretKey=your_encryption_key \
 -p 5000:5000 ug-ecr-reverse-proxy

You will find your LICENSE_KEY in the welcome email, or you can contact support to obtain a new one.

Generate a 32 bytes (256 bits) long ENCRYPTION_KEY and pass it when starting a container, this key is used to encrypt yoru API Keys at rest.

openssl rand -base64 32

Configure authentication setttings

Go to "App" section in appsettings.json and edit the Cors, and Auth section:

"App": {
    ...
    "Cors": {
      "AllowedOrigins": [
        ...
        "https://app.usageguard.com"
      ]
    }
  },

"Auth": {
      "SecretKey": "genrate-random-key",
      "Issuer": "your-backend-api-url",
      "Audience": "your-front-end-url",
      "VerifyAudience": true,
      "RefreshTokenExpirationDays": 7,
      "SigningKeyType": "Symmetric",
      "Domain": ".example.com"
    }

UsageGuard App

docker run -d --name ug-prod-app \
  -e NODE_ENV=production \
  -e API_HOST=https://your-host-url \
  -p 3000:3000 \
  ug-ecr-reverse-proxy-app

You need to provide settings for PostgreSQL, OpenSearch and Authentication, detailed guide below.

In addition, you will also need to configure your API_HOST in ug-ecr-reverse-proxy_app (Image for UG app) default settings with your custom api host in .env.production

Alternativly you pass API_HOST environment variable directly when starting ug-ecr-reverse-proxy_app container.

Locating and editing .env.production and edit the following line:

API_HOST=https://your-api-host

Dependencies

OpenSearch

Create an OpenSearch cluster if you don't have one already, we recommend following these confiugration but it depends on your expected usage.

UsageGuard uses two index system to store traces and sessions, execute the following commands to create these indexes in your OpenSearch instance.

Locate the two mapping files trace_log_mapping.json and sessions_log_mapping.json to use in creating the indexes:

Run the following commands using cURL or any HTTP client passing the mapping file

Creating Traces and Sessions Indexes

Traces

curl -u "user:password" -X PUT "$ENDPOINT/choose-name-for-traces-index" -H "Content-Type: application/json" --data-binary "@trace_log_mapping.json"

Sessions

curl -u "user:password" -X PUT "$ENDPOINT/choose-name-for-sessions-index" -H "Content-Type: application/json" --data-binary "@trace_log_mapping.json"

You should receive a response for each call similar to this:

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "your-index-name"
}

To further verify these indexes are created correctly, call:

curl -u "user:password" -X GET "$ENDPOINT/_cluster/health/your-index-name?pretty"

Go to "OpenSearch" section in appsettings.json and edit the OpenSearch section:

"OpenSearch": {
      "Url": "your-open-search-endpoint",    
      "LogIndex": "your-trace-index-name",
      "SessionIndex": "your-sessions-index-name",
      "Username": "your-open-search-username",
      "Password": "your-open-search-password"
    },

PostgreSQL

Create a PostgreSQL database and give it a name, locate the file usage-guard-db_3_1_0.sql and run the following commands to create the required tables and populate them with the nesessary data.

Local or Remote

PGPASSWORD="your_password" psql -U your_user -d your_database -h your_host -f usage-guard-db_3_1_0.sql

Docker

docker exec -i your_pg_container psql -U your_user -d your_database -h your_host -W your_password < usage-guard-db_3_1_0.sql

Configuration

Go to ConnectionStrings section in appsettings.json and edit the default connection string value:

"DefaultConnection": "Server=your-database-cluster;Port=5432;Database=database-name;User Id=user;Password=password;Include Error Detail=True;"

Now all the core requirements to install UsageGuard are ready.

Inference and RAG Providers

For UsageGuard to be able to execute inference requests you must configure at least one of the following providers:

• OpenAI
• Ollama
• AWS Bedrock

If you want to use RAG you need to confiure at least one per category:

• Vector Database (Pinecone or Qdrant)
• Vector Embedding Mode (You can choose an embedding model from any inference provider you configured and enabled)
• Object Storage (Amazon S3 or MinIO)

Browse to your front-end endpoint, click settings in the bottom of the side bar and choose Integrations and add your api keys and other configurations for inference, vector databases, embedding models and object storage.

Contact support@usageguard.com for token requests or any other enquires.