Back to Details

perses-deploy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Perses Deploy

Perses 部署指南

Deploy and configure Perses server instances across different environments.
在不同环境中部署和配置Perses服务器实例。

Operator Context

操作者说明

This skill operates as a deployment guide for Perses server instances, covering local development, Kubernetes, and bare metal deployments.
本技能作为Perses服务器实例的部署指南，涵盖本地开发、Kubernetes和裸金属服务器部署场景。

Hardcoded Behaviors (Always Apply)

强制遵循规则（始终适用）

  • Never expose admin credentials in plain text — use environment variables or secrets
  • Always configure auth for non-local deployments — at minimum enable native auth
  • Validate connectivity after deployment — check 
    /api/v1/projects
    endpoint responds
  • 切勿以明文形式暴露管理员凭证——请使用环境变量或机密存储
  • 非本地部署必须配置认证——至少启用原生认证
  • 部署后验证连通性——检查
    /api/v1/projects
    端点是否正常响应

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则生效）

  • Local dev default: Docker with file-based storage if deployment target not specified
  • Plugin loading: Configure official plugins from perses/plugins repository
  • Health check: Verify Perses is running and API is accessible after deployment
  • 本地开发默认配置：若未指定部署目标，默认使用Docker搭配文件型存储
  • 插件加载：配置来自perses/plugins仓库的官方插件
  • 健康检查：部署后验证Perses是否正常运行且API可访问

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则不生效）

  • Production hardening: TLS, OIDC auth, SQL database, resource limits
  • Kubernetes operator: Deploy via perses-operator CRDs instead of Helm
  • MCP server setup: Install and configure perses-mcp-server alongside Perses
  • 生产环境加固：TLS加密、OIDC认证、SQL数据库、资源限制
  • Kubernetes Operator部署：使用perses-operator CRDs替代Helm进行部署
  • MCP服务器设置：在Perses旁安装并配置perses-mcp-server

What This Skill CAN Do

本技能可实现的功能

  • Deploy Perses via Docker, Helm, binary, or K8s operator
  • Configure server settings: database, auth, plugins, provisioning, frontend
  • Set up MCP server integration for Claude Code
  • Verify deployment health and connectivity
  • 通过Docker、Helm、二进制包或K8s Operator部署Perses
  • 配置服务器设置：数据库、认证、插件、资源配置、前端
  • 为Claude Code设置MCP服务器集成
  • 验证部署健康状态与连通性

What This Skill CANNOT Do

本技能无法实现的功能

  • Create or manage dashboards (use perses-dashboard-create)
  • Develop plugins (use perses-plugin-create)
  • Manage Kubernetes clusters (use kubernetes-helm-engineer)
  • 创建或管理仪表板（请使用perses-dashboard-create）
  • 开发插件（请使用perses-plugin-create）
  • 管理Kubernetes集群（请使用kubernetes-helm-engineer）

Instructions

操作步骤

Phase 1: ASSESS Environment

阶段1：环境评估

Goal: Determine deployment target and requirements.
  1. Deployment target: Docker (local dev), Helm (Kubernetes), Binary (bare metal), or Operator (K8s CRDs)
  2. Storage backend: File-based (default, no external DB needed) or SQL (MySQL)
  3. Authentication: None (local dev), Native (username/password), OIDC, OAuth, or K8s ServiceAccount
  4. Plugin requirements: Official plugins only, or custom plugins too?
  5. MCP integration: Should we also set up the Perses MCP server for Claude Code?
Gate: Environment assessed. Proceed to Phase 2.
目标：确定部署目标与需求。
  1. 部署目标：Docker（本地开发）、Helm（Kubernetes）、二进制包（裸金属）或Operator（K8s CRDs）
  2. 存储后端：文件型（默认，无需外部数据库）或SQL（MySQL）
  3. 认证方式：无（仅本地开发）、原生（用户名/密码）、OIDC、OAuth或K8s ServiceAccount
  4. 插件需求：仅使用官方插件，还是也需要自定义插件？
  5. MCP集成：是否需要同时为Claude Code配置Perses MCP服务器？
阶段完成标志：环境评估完成，进入阶段2。

Phase 2: DEPLOY

阶段2：部署

Goal: Deploy Perses server.
目标：部署Perses服务器。

Option A: Docker (Local Development)

选项A：Docker（本地开发）

bash
undefined
bash
undefined

Simplest — single container with defaults

最简方式——使用默认配置的单容器

docker run --name perses -d -p 127.0.0.1:8080:8080 persesdev/perses
docker run --name perses -d -p 127.0.0.1:8080:8080 persesdev/perses

With custom config

自定义配置启动

docker run --name perses -d -p 127.0.0.1:8080:8080
-v /path/to/config.yaml:/etc/perses/config.yaml
-v /path/to/data:/perses/data
persesdev/perses --config=/etc/perses/config.yaml
undefined
docker run --name perses -d -p 127.0.0.1:8080:8080
-v /path/to/config.yaml:/etc/perses/config.yaml
-v /path/to/data:/perses/data
persesdev/perses --config=/etc/perses/config.yaml
undefined

Option B: Helm (Kubernetes)

选项B：Helm（Kubernetes）

bash
helm repo add perses https://perses.github.io/helm-charts
helm repo update
helm install perses perses/perses \
  --namespace perses --create-namespace \
  --set config.database.file.folder=/perses/data \
  --set config.security.enable_auth=true
bash
helm repo add perses https://perses.github.io/helm-charts
helm repo update
helm install perses perses/perses \
  --namespace perses --create-namespace \
  --set config.database.file.folder=/perses/data \
  --set config.security.enable_auth=true

Option C: Binary (Bare Metal)

选项C：二进制包（裸金属）

bash
undefined
bash
undefined

Install via Homebrew

通过Homebrew安装

brew install perses/tap/perses brew install perses/tap/percli
brew install perses/tap/perses brew install perses/tap/percli

Or download from GitHub releases

或从GitHub Releases下载安装包

Run with config

使用配置文件启动

perses --config=./config.yaml
undefined
perses --config=./config.yaml
undefined

Option D: Kubernetes Operator

选项D：Kubernetes Operator

bash
helm repo add perses https://perses.github.io/helm-charts
helm install perses-operator perses/perses-operator \
  --namespace perses-system --create-namespace
bash
helm repo add perses https://perses.github.io/helm-charts
helm install perses-operator perses/perses-operator \
  --namespace perses-system --create-namespace

Then create a Perses CR

然后创建Perses自定义资源（CR）

cat <<EOF | kubectl apply -f - apiVersion: perses.dev/v1alpha2 kind: Perses metadata: name: perses namespace: perses spec: config: database: file: folder: '/perses' extension: 'yaml' containerPort: 8080 EOF

**Gate**: Perses server deployed. Proceed to Phase 3.
cat <<EOF | kubectl apply -f - apiVersion: perses.dev/v1alpha2 kind: Perses metadata: name: perses namespace: perses spec: config: database: file: folder: '/perses' extension: 'yaml' containerPort: 8080 EOF

**阶段完成标志**：Perses服务器部署完成，进入阶段3。

Phase 3: CONFIGURE

阶段3：配置

Goal: Configure server settings.
Server configuration (config.yaml):
yaml
undefined
目标：配置服务器设置。
服务器配置文件（config.yaml）：
yaml
undefined

Database

数据库配置

database: file: folder: "/perses/data" extension: "yaml"
database: file: folder: "/perses/data" extension: "yaml"

Security

安全配置

security: readonly: false enable_auth: true encryption_key: "<32-byte-AES-256-key>" authentication: access_token_ttl: "15m" refresh_token_ttl: "24h" providers: enable_native: true # oidc: # - slug_id: github # name: "GitHub" # client_id: "<client-id>" # client_secret: "<client-secret>" # issuer: "https://github.com" # redirect_uri: "https://perses.example.com/api/auth/providers/oidc/github/callback"
security: readonly: false enable_auth: true encryption_key: "<32-byte-AES-256-key>" authentication: access_token_ttl: "15m" refresh_token_ttl: "24h" providers: enable_native: true # oidc: # - slug_id: github # name: "GitHub" # client_id: "<client-id>" # client_secret: "<client-secret>" # issuer: "https://github.com" # redirect_uri: "https://perses.example.com/api/auth/providers/oidc/github/callback"

Plugins

插件配置

plugin: archive_path: "plugins-archive" path: "plugins"
plugin: archive_path: "plugins-archive" path: "plugins"

Provisioning (auto-load resources from folders)

资源自动加载配置（从文件夹自动加载资源）

provisioning: folders: - "/perses/provisioning"
provisioning: folders: - "/perses/provisioning"

Frontend

前端配置

frontend: time_range: disable_custom: false

**Environment variables** override config with `PERSES_` prefix:
- `PERSES_DATABASE_FILE_FOLDER=/perses/data`
- `PERSES_SECURITY_ENABLE_AUTH=true`
- `PERSES_SECURITY_ENCRYPTION_KEY=<key>`

**Gate**: Configuration applied. Proceed to Phase 4.
frontend: time_range: disable_custom: false

**环境变量**可覆盖配置文件，前缀为`PERSES_`：
- `PERSES_DATABASE_FILE_FOLDER=/perses/data`
- `PERSES_SECURITY_ENABLE_AUTH=true`
- `PERSES_SECURITY_ENCRYPTION_KEY=<key>`

**阶段完成标志**：配置已应用，进入阶段4。

Phase 4: VALIDATE

阶段4：验证

Goal: Verify deployment is healthy.
bash
undefined
目标：验证部署是否健康。
bash
undefined

Check API is responding

检查API是否正常响应

curl -s http://localhost:8080/api/v1/projects | head
curl -s http://localhost:8080/api/v1/projects | head

Install percli and login

安装percli并登录

percli login http://localhost:8080 --username admin --password <password> percli whoami
percli login http://localhost:8080 --username admin --password <password> percli whoami

Create a test project

创建测试项目

percli apply -f - <<EOF kind: Project metadata: name: test spec: {} EOF
percli apply -f - <<EOF kind: Project metadata: name: test spec: {} EOF

Verify

验证项目是否存在

percli get project

**Optional: Set up MCP server**

```bash
percli get project

**可选：设置MCP服务器**

```bash

Install perses-mcp-server from releases

从Releases安装perses-mcp-server

Create config

创建配置文件

cat > perses-mcp-config.yaml <<EOF transport: stdio read_only: false perses_server: url: "http://localhost:8080" native_auth: login: "admin" password: "<password>" EOF
cat > perses-mcp-config.yaml <<EOF transport: stdio read_only: false perses_server: url: "http://localhost:8080" native_auth: login: "admin" password: "<password>" EOF

Add to Claude Code settings.json

添加到Claude Code的settings.json中

mcpServers.perses.command = "perses-mcp-server"

mcpServers.perses.command = "perses-mcp-server"

mcpServers.perses.args = ["--config", "/path/to/perses-mcp-config.yaml"]

mcpServers.perses.args = ["--config", "/path/to/perses-mcp-config.yaml"]


**Gate**: Deployment verified, connectivity confirmed. Task complete.

**阶段完成标志**：部署验证通过，连通性确认。任务完成。