### Getting Started: Installation and Development Server

Source: https://github.com/msgbyte/tianji/blob/master/example/web/README.md

Instructions to navigate to the project directory, install dependencies, and start the development server.

```bash
cd example/web
npm install
npm run dev
```

--------------------------------

### First API Call with curl

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/getting-started.md

Example of making the first API call to get global configuration using curl.

```bash
curl -X GET "https://your-tianji-domain.com/open/global/config" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"
```

--------------------------------

### Run Server

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/install/manual.md

Installs pm2 globally, configures log rotation, applies database migrations, and starts the Tianji server using pm2.

```bash
npm install pm2 -g && pm2 install pm2-logrotate

# Init db migrate
cd src/server
pnpm db:migrate:apply

# Start Server
pm2 start ./dist/src/server/main.js --name tianji
```

--------------------------------

### Development Commands

Source: https://github.com/msgbyte/tianji/blob/master/AGENTS.md

Commands for setting up local development environment, including installing dependencies, starting the server, and building production assets.

```shell
pnpm install
pnpm dev
pnpm build
```

--------------------------------

### Install SDK

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/openapi-sdk.md

Install the Tianji OpenAPI SDK using npm, yarn, or pnpm.

```bash
npm install tianji-client-sdk
# or
yarn add tianji-client-sdk
# or
pnpm add tianji-client-sdk
```

--------------------------------

### API Base URL

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/getting-started.md

The base URL for all Tianji API requests.

```bash
https://your-tianji-domain.com/open
```

--------------------------------

### Enable OpenAPI Environment Variable

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/getting-started.md

Environment variable to enable OpenAPI access in Tianji.

```bash
ALLOW_OPENAPI=true
```

--------------------------------

### Tianji Installation and Configuration

Source: https://github.com/msgbyte/tianji/blob/master/website/blog/2025-11-12-real-time-performance-monitoring-and-observability.md

Commands to download and start Tianji using Docker Compose, and instructions to access the admin interface.

```bash
# 1. Download and start Tianji
wget https://raw.githubusercontent.com/msgbyte/tianji/master/docker-compose.yml
docker compose up -d

# 2. Access the admin interface
# http://localhost:12345
# Default credentials: admin / admin (change password immediately)
```

--------------------------------

### cURL Example

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/authentication.md

Example of how to make an authenticated GET request using cURL.

```bash
curl -X GET "https://your-tianji-domain.com/open/global/config" \
  -H "Authorization: Bearer <your_api_key_here>" \
  -H "Content-Type: application/json"
```

--------------------------------

### Python Example

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/authentication.md

Example of how to make an authenticated GET request using Python with the requests library.

```python
import requests

api_key = '<your_api_key_here>'
base_url = 'https://your-tianji-domain.com/open'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

# Using requests library
response = requests.get(f'{base_url}/global/config', headers=headers)
data = response.json()
```

--------------------------------

### Installation

Source: https://github.com/msgbyte/tianji/blob/master/website/README.md

Installs project dependencies using Yarn.

```bash
$ yarn
```

--------------------------------

### Install Tianji

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/install/kubernetes/helm.md

Installs Tianji using the msgbyte/tianji Helm chart.

```bash
helm install tianji msgbyte/tianji
```

--------------------------------

### JavaScript/Node.js Example

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/authentication.md

Example of how to make an authenticated GET request using JavaScript with fetch and axios.

```javascript
const apiKey = '<your_api_key_here>';
const baseUrl = 'https://your-tianji-domain.com/open';

const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

// Using fetch
const response = await fetch(`${baseUrl}/global/config`, {
  method: 'GET',
  headers: headers
});

// Using axios
const axios = require('axios');
const response = await axios.get(`${baseUrl}/global/config`, {
  headers: headers
});
```

--------------------------------

### Clone Code and Build

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/install/manual.md

Clones the Tianji repository, navigates into the directory, installs dependencies, and builds the project.

```bash
git clone https://github.com/msgbyte/tianji.git
cd tianji
pnpm install

pnpm build
```

--------------------------------

### PHP Example

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/authentication.md

Example of how to make an authenticated GET request using PHP with cURL.

```php
<?php
$apiKey = '<your_api_key_here>';
$baseUrl = 'https://your-tianji-domain.com/open';

$headers = [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/global/config');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
?>
```

--------------------------------

### Configure DATABASE_URL

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/dev/prepare.md

Example of how to configure the DATABASE_URL in the .env file.

```ini
DATABASE_URL="postgresql://tianji:tianji@localhost:5432/tianji?schema=public"
ALLOW_OPENAPI=true
```

--------------------------------

### Installation from NPM (When Published)

Source: https://github.com/msgbyte/tianji/blob/master/packages/cli/README.md

Instructions for installing the CLI from NPM when it is published.

```bash
npm install -g tianji-cli
# or
pnpm add -g tianji-cli
```

--------------------------------

### Example 1: Get All Survey List

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/mcp/mcp.md

User interaction to get all survey lists and AI assistant's response including a call to the MCP protocol.

```text
User: Help me view all my survey questionnaire lists

AI Assistant: I'll get all your survey questionnaire lists for you.
[AI Assistant calls tianji_get_all_survey_list through MCP protocol to get data]
Based on the data in your workspace, you currently have the following surveys:
1. User Experience Satisfaction Survey (created on 2023-09-15)
2. Product Feature Feedback Survey (created on 2023-10-01)
3. Website Usability Assessment (created on 2023-10-20)
```

--------------------------------

### Quick Start with Tianji Alert System

Source: https://github.com/msgbyte/tianji/blob/master/website/blog/2025-10-19-building-intelligent-alert-systems-from-noise-to-signal.md

Commands to download and start the Tianji alert system using Docker Compose.

```bash
# Download and start Tianji
wget https://raw.githubusercontent.com/msgbyte/tianji/master/docker-compose.yml
docker compose up -d
```

--------------------------------

### Installation

Source: https://github.com/msgbyte/tianji/blob/master/apps/daily-ai-trigger/README.md

Installs project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Local Development

Source: https://github.com/msgbyte/tianji/blob/master/website/README.md

Starts a local development server for live previewing changes.

```bash
$ yarn start
```

--------------------------------

### Start the App

Source: https://github.com/msgbyte/tianji/blob/master/example/expo/README.md

Starts the Expo development server to run the application.

```bash
npx expo start
```

--------------------------------

### Development Start

Source: https://github.com/msgbyte/tianji/blob/master/apps/daily-ai-trigger/README.md

Starts the development server for scheduled tasks.

```bash
npm run dev:scheduled
```

--------------------------------

### Installation from Source (Development)

Source: https://github.com/msgbyte/tianji/blob/master/packages/cli/README.md

Instructions for installing the CLI from source for development purposes within the Tianji monorepo.

```bash
# In the Tianji monorepo root
pnpm install
cd packages/cli
pnpm build

# Link globally for development
pnpm link --global
```

--------------------------------

### Example URL with parameters

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/telemetry/params.md

Demonstrates how to include various parameters in the telemetry URL.

```url
https://tianji.example.com/telemetry/<workspaceId>/<telemetryId>/badge.svg?name=myEvent&url=https://google.com&title=My+Counter&start=100000&fullNum=true
```

--------------------------------

### Install Dependencies

Source: https://github.com/msgbyte/tianji/blob/master/example/expo/README.md

Installs the necessary dependencies for the Expo project.

```bash
npm install
```

--------------------------------

### Search for Tianji chart

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/install/kubernetes/helm.md

Searches your Helm repositories for the Tianji chart.

```bash
helm search repo tianji
```

--------------------------------

### Python Example

Source: https://github.com/msgbyte/tianji/blob/master/website/static/llms-full.txt

Example of how to make an API request using Python with Bearer Token authentication.

```php
$baseUrl = 'https://your-tianji-domain.com/open';

$headers = [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/global/config');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
?>
```

--------------------------------

### Complete docker-compose.yml Example

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/install/docker-monitoring.md

A complete example of a `docker-compose.yml` file with the Docker Socket mapping included for Tianji service.

```yaml
version: '3'
services:
  tianji:
    image: moonrailgun/tianji
    build:
      context: ./ 
      dockerfile: ./Dockerfile
    ports:
      - "12345:12345"
    environment:
      DATABASE_URL: postgresql://tianji:tianji@postgres:5432/tianji
      JWT_SECRET: replace-me-with-a-random-string
      ALLOW_REGISTER: "false"
      ALLOW_OPENAPI: "true"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # Add this line
    depends_on:
      - postgres
    restart: always
  postgres:
    # ... postgres configuration ...
```

--------------------------------

### Database Sync Jobs Monitoring Example

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/monitor/push-monitor.md

Python example using schedule library to monitor database sync jobs and send status to Tianji.

```python
import requests
import schedule
import time

def sync_data():
    try:
        # Your data sync logic here
        result = perform_data_sync()
        
        if result.success:
            requests.post(
                'https://tianji.example.com/api/push/<your-push-token>',
                params={'status': 'up', 'msg': f'synced-{result.records}-records'}
            )
        else:
            requests.post(
                'https://tianji.example.com/api/push/<your-push-token>',
                params={'status': 'down', 'msg': 'sync-failed'}
            )
    except Exception as e:
        requests.post(
            'https://tianji.example.com/api/push/<your-push-token>',
            params={'status': 'down', 'msg': f'error-{str(e)}'}
        )

# Schedule to run every hour
schedule.every().hour.do(sync_data)

while True:
    schedule.run_pending()
    time.sleep(1)
```

--------------------------------

### Docker Compose Installation

Source: https://github.com/msgbyte/tianji/blob/master/website/blog/2025-08-31-privacy-first-website-analytics-with-tianji.md

Install Tianji using Docker Compose for full data control.

```bash
wget https://raw.githubusercontent.com/msgbyte/tianji/master/docker-compose.yml
docker compose up -d
```

--------------------------------

### Update Channel Example

Source: https://github.com/msgbyte/tianji/blob/master/website/static/llms-full.txt

Example using curl to update notification targets for a channel.

```bash
curl -X POST \
  "$BASE_URL/workspace/$WORKSPACE_ID/feed/$CHANNEL_ID/update" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "name": "Ops", \
    "notifyFrequency": 60, \
    "notificationIds": ["notif_123", "notif_456"] \
  }'
```

--------------------------------

### Install the Tianji react native SDK

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/application/tracking.md

Install the Tianji react native SDK in your project using npm, yarn, or pnpm.

```bash
npm install tianji-react-native
# or
yarn add tianji-react-native
# or
pnpm add tianji-react-native
```

--------------------------------

### Add Helm repository

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/install/kubernetes/helm.md

Adds the msgbyte charts registry to your Helm repositories.

```bash
helm repo add msgbyte https://msgbyte.github.io/charts
```

--------------------------------

### Dynamic Baseline Calculation Example

Source: https://github.com/msgbyte/tianji/blob/master/website/blog/2025-11-12-real-time-performance-monitoring-and-observability.md

An example of how dynamic baselines can be calculated using historical data, including mean, standard deviation, and confidence thresholds for warnings and critical alerts.

```typescript
{
  metric: "cpu_usage",
  baseline: {
    mean: 45.2,      // Historical average
    stdDev: 8.3,     // Standard deviation
    confidence: 95,  // Confidence interval
    threshold: {
      warning: 61.8,   // mean + 2*stdDev
      critical: 70.1   // mean + 3*stdDev
    }
  }
}
```

--------------------------------

### Copy .env.example to .env

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/dev/prepare.md

Copies the example environment file to be used for server configuration.

```bash
cp .env.example src/server/.env
```

--------------------------------

### Apply Database Migrations

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/dev/prepare.md

Navigates to the server directory and applies database migrations.

```bash
cd src/server && pnpm db:migrate:apply
```

--------------------------------

### HTTP Method-Based Worker Example

Source: https://github.com/msgbyte/tianji/blob/master/packages/cli/README.md

An example worker that handles different HTTP methods (GET, POST).

```typescript
export default async function handler(payload: any, context: any) {
  if (context.type !== 'http') {
    return { error: 'Only HTTP requests supported' };
  }

  const method = context.request?.method;
  
  switch (method) {
    case 'GET':
      return { message: 'Hello GET' };
    case 'POST':
      return { message: 'Data received', data: payload };
    default:
      return { error: 'Method not supported' };
  }
}
```

--------------------------------

### Run PostgreSQL Docker Container

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/dev/prepare.md

Starts a PostgreSQL container named 'tianji-pg' with specified environment variables for database name, user, and password.

```bash
docker run --name tianji-pg -e POSTGRES_DB=tianji -e POSTGRES_USER=tianji -e POSTGRES_PASSWORD=tianji -d postgres:15.4-alpine
```

--------------------------------

### Example 2: Get Specific Survey Details

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/mcp/mcp.md

User interaction to get specific survey details and AI assistant's response including a call to the MCP protocol.

```text
User: Please tell me the details of the "User Experience Satisfaction Survey"

AI Assistant: I'll query the details of that survey for you.
[AI Assistant calls tianji_get_survey_info through MCP protocol to get data]
Details of the "User Experience Satisfaction Survey":
- Creation time: 2023-09-15
- Status: Active
- Number of questions: 10
- Responses collected: 128
- Most recent response: 2023-10-25
```

--------------------------------

### Install and Configure Server Monitoring Client

Source: https://github.com/msgbyte/tianji/blob/master/website/blog/2025-11-12-real-time-performance-monitoring-and-observability.md

Commands to download, make executable, and configure the Tianji server monitoring client for real-time data collection from servers.

```bash
# Install server monitoring client
curl -o tianji-reporter https://tianji.example.com/download/reporter
chmod +x tianji-reporter

# Configure and start
./tianji-reporter \
  --workspace-id="your-workspace-id" \
  --name="production-server-1" \
  --interval=5
```

--------------------------------

### Get System Configuration

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/openapi-sdk.md

Retrieve the system configuration using the openApiClient.GlobalService.globalConfig() method.

```javascript
import { openApiClient } from 'tianji-client-sdk';

async function getSystemConfig() {
  try {
    const config = await openApiClient.GlobalService.globalConfig();
    
    console.log('Allow registration:', config.allowRegister);
    console.log('AI features enabled:', config.ai.enable);
    console.log('Billing enabled:', config.enableBilling);
    
    return config;
  } catch (error) {
    console.error('Failed to get system configuration:', error);
  }
}
```

--------------------------------

### Prepare Environment File

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/install/manual.md

Creates a .env file in the src/server directory with essential configuration variables.

```ini
DATABASE_URL="postgresql://user:pass@127.0.0.1:5432/tianji?schema=public"
JWT_SECRET="replace-me-with-a-random-string"
```

--------------------------------

### Build

Source: https://github.com/msgbyte/tianji/blob/master/website/README.md

Generates static content for deployment.

```bash
$ yarn build
```

--------------------------------

### 403 Forbidden Error Example

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/authentication.md

Example JSON response for a 403 Forbidden error.

```json
{
  "error": {
    "code": "FORBIDDEN", 
    "message": "Insufficient access"
  }
}
```

--------------------------------

### 401 Unauthorized Error Example

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/authentication.md

Example JSON response for a 401 Unauthorized error.

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authorization not provided"
  }
}
```

--------------------------------

### Complete docker-compose.yml Example

Source: https://github.com/msgbyte/tianji/blob/master/website/static/llms-full.txt

A complete docker-compose.yml file including the Docker socket volume for Tianji.

```yaml
version: '3'
services:
  tianji:
    image: moonrailgun/tianji
    build:
      context: ./ 
      dockerfile: ./Dockerfile
    ports:
      - "12345:12345"
    environment:
      DATABASE_URL: postgresql://tianji:tianji@postgres:5432/tianji
      JWT_SECRET: replace-me-with-a-random-string
      ALLOW_REGISTER: "false"
      ALLOW_OPENAPI: "true"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # Add this line
    depends_on:
      - postgres
    restart: always
  postgres:
    # ... postgres configuration ...

```

--------------------------------

### Initialize OpenAPI Client

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/api/openapi-sdk.md

Initialize the OpenAPI SDK with your Tianji domain and API key.

```javascript
import { initOpenapiSDK } from 'tianji-client-sdk';

initOpenapiSDK('https://your-tianji-domain.com', {
  apiKey: 'your-api-key'
});
```

--------------------------------

### Simple Echo Worker Example

Source: https://github.com/msgbyte/tianji/blob/master/packages/cli/README.md

An example of a simple worker that echoes the received payload.

```typescript
export default async function handler(payload: any) {
  return {
    echo: payload,
    timestamp: new Date().toISOString(),
  };
}
```

--------------------------------

### Worker Handler Function Example

Source: https://github.com/msgbyte/tianji/blob/master/packages/cli/README.md

Example of a basic worker handler function in TypeScript.

```typescript
export default async function handler(payload: any, context: any) {
  // Your worker logic here
  return {
    success: true,
    message: 'Hello from Tianji Worker!',
    data: payload,
  };
}
```

--------------------------------

### Initialize Tianji Tracker and Report Event with SDK

Source: https://github.com/msgbyte/tianji/blob/master/website/static/llms-full.txt

Example of initializing the Tianji tracker and reporting an event using the SDK.

```javascript
initTianjiTracker({
  url: backendUrl,
  websiteId,
});

reportEvent('Demo Event', {
  foo: 'bar',
});
```

--------------------------------

### Resolve isolated-vm installation failure with Python 3.12

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/install/manual.md

Commands to resolve the 'ModuleNotFoundError: No module named 'distutils'' error when installing isolated-vm with Python 3.12 by switching to Python 3.9 using Homebrew.

```bash
brew install python@3.9
rm /opt/homebrew/bin/python3
ln -sf /opt/homebrew/bin/python3 /opt/homebrew/bin/python3.9
```

--------------------------------

### 403 Forbidden Error Example

Source: https://github.com/msgbyte/tianji/blob/master/website/static/llms-full.txt

Example JSON response for a 403 Forbidden error.

```json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient access"
  }
}
```

--------------------------------

### Cron Worker Example

Source: https://github.com/msgbyte/tianji/blob/master/packages/cli/README.md

An example worker designed to run on a schedule via cron triggers.

```typescript
export default async function handler(payload: any, context: any) {
  if (context.type === 'cron') {
    // Perform scheduled task
    console.log('Cron job executed at:', new Date().toISOString());
    return { success: true };
  }
  
  return { error: 'This worker only runs on schedule' };
}
```

--------------------------------

### Add Plugin in Static Configuration (Command Line)

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/website/framework/install-in-traefik-with-plugin.md

Add the plugin reference using command-line arguments.

```bash
--experimental.plugins.traefik-tianji-plugin.modulename=github.com/msgbyte/traefik-tianji-plugin
--experimental.plugins.traefik-tianji-plugin.version=v0.2.1
```

--------------------------------

### Example Scenario: Server Response Slowdown

Source: https://github.com/msgbyte/tianji/blob/master/website/blog/2025-10-19-building-intelligent-alert-systems-from-noise-to-signal.md

This example demonstrates how Tianji correlates data from different monitoring sources (Server Status, Uptime Monitor, Website Analytics) to assess a server response slowdown scenario and determine if it's a normal traffic spike or a system failure.

```bash
# Example scenario: Server response slowdown
- Server Status: CPU utilization at 85%
- Uptime Monitor: Response time increased from 200ms to 1500ms
- Website Analytics: User traffic surged by 300%

→ Tianji's intelligent assessment: This is a normal traffic spike, not a system failure
```

--------------------------------

### Full Tracker Script Example with Attributes

Source: https://github.com/msgbyte/tianji/blob/master/website/docs/website/track-script.md

An example of the tracker script with all supported data attributes.

```html
<script
  async
  defer
  src="https://example.com/tracker.js"
  data-website-id="clxxxxxxxxxxxxxxxxxx"
  data-host-url="https://analytics.example.com"
  data-auto-track="true"
  data-do-not-track="true"
  data-domains="example.com,www.example.com"
></script>
```