FilesLast commitLast update
1 month ago
1 month ago
1 month ago
26 days ago
26 days ago
26 days ago
2 months ago
4 days ago
1 month ago
1 month ago
1 month ago
2 months ago
26 days ago
26 days ago
26 days ago
4 days ago
4 days ago
2 months ago
README

RuleGo Server

Docs | 中文

An application development scaffold based on RuleGo, for rapidly building AI agent, IoT, workflow and other applications.

Architecture Overview

RuleGo Server uses a layered modular architecture where every layer can be customized:

┌──────────────────────────────────────────────────┐
│  Host Application (Gin / Echo / Standalone)      │
├──────────────────────────────────────────────────┤
│  Bridge Layer (adapts to standard http.Handler)   │
├──────────────────────────────────────────────────┤
│  App Lifecycle + Container (Service Container)    │
│  ┌──────────┬──────────┬──────────┬───────────┐  │
│  │ Module   │ Module   │ Module   │  Custom    │  │
│  │ (rule)   │ (user)   │ (mcp)    │  Module   │  │
│  └──────────┴──────────┴──────────┴───────────┘  │
├──────────────────────────────────────────────────┤
│  Store Layer (File / Database / Custom)           │
└──────────────────────────────────────────────────┘

Key extension points:

  • Modules: Implement the app.Module interface, inject via WithModules() or replace via WithModuleOverride()
  • Storage: Implement the store.StoreProvider interface, replace default file storage via WithStoreProvider()
  • Auth: Implement Authenticator / Authorizer interfaces to replace JWT and allow-all defaults
  • Hooks: Insert logic at 5 lifecycle phases via WithHooks()
  • Components: Load AI, IoT and other component packages on demand via build tags

Directory Structure

server/
├── cmd/server/                # Server entry point (with component registration via with_*.go)
├── app/                       # Public: App core (lifecycle, Container, Module interface)
├── bootstrap/                 # Public: Default module assembly
├── bridge/                    # Public: Host system bridge layer (Gin/Echo etc.)
├── config/                    # Public: Configuration management
├── model/                     # Public: Pure data models
├── services/                  # Public: Stable service interfaces exported by modules
├── store/                     # Public: Storage interfaces (for custom storage implementations)
├── internal/                  # Internal implementation (compile-time protected, not importable)
│   ├── modules/              #   Business module implementations
│   │   ├── rule/             #     Rule chain module
│   │   ├── user/             #     User module
│   │   ├── node/             #     Node pool module
│   │   ├── runlog/           #     Run log module
│   │   ├── locale/           #     i18n module
│   │   ├── skill/            #     Skill module
│   │   ├── debug/            #     Debug module
│   │   ├── system/           #     System config module
│   │   ├── marketplace/      #     Marketplace module
│   │   └── mcp/              #     MCP module
│   ├── store/                #   Storage implementations
│   │   └── filestore/        #     File-based storage
│   ├── endpoint/             #   REST endpoint server
│   ├── engine/               #   Rule engine management
│   ├── registry/             #   Built-in registry
│   ├── constants/            #   Constants and errors
│   └── utils/                #   Utility functions
├── config.conf               # Default configuration
└── data/                     # Data directory

Quick Start

Option 1: Run the server directly

cd rulego/server

# Basic version
go run ./cmd/server

# With AI components
go build -tags with_ai ./cmd/server && ./server

# With all optional components
go build -tags with_all ./cmd/server && ./server

# With specific components
go build -tags with_ai,with_iot ./cmd/server && ./server

Option 2: Import as a package

package main

import (
    "github.com/rulego/rulego/server/app"
    "github.com/rulego/rulego/server/bootstrap"

    // Import components as needed (see cmd/server/with_*.go)
    _ "github.com/rulego/rulego-components-ai/agent"
    _ "github.com/rulego/rulego-components-ai/tool/bash"
    // ... other components
)

func main() {
    application, _ := app.New(
        app.WithConfigFile("config.conf"),
        app.WithModules(bootstrap.DefaultModules()...),
    )
    application.Run()
}

Option 3: Embedded integration (Gin example)

Use bridge.Bridge to bridge the full RuleGo REST API into your host framework — no manual route registration needed.

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/rulego/rulego/server/app"
    "github.com/rulego/rulego/server/bootstrap"
    "github.com/rulego/rulego/server/bridge"
)

func main() {
    application, _ := app.New(
        app.WithConfigFile("config.conf"),
        app.WithModules(bootstrap.DefaultModules()...),
    )
    b, _ := bridge.NewBridge(application)
    defer b.Stop()

    r := gin.Default()

    // Your own routes (matched first)
    r.GET("/api/users", userListHandler)

    // Full RuleGo API — unmatched routes fall through to the Bridge handler
    r.Any("/*path", gin.WrapH(b.Handler()))

    _ = r.Run(":8080")
}

Shortcut with default modules:

b, _ := bridge.NewBridgeWithDefaults("config.conf")
defer b.Stop()
handler := b.Handler() // standard http.Handler

Deployment

One-click install for three targets (details in deploy/):

Docker / Docker Compose

curl -fsSL https://raw.githubusercontent.com/rulego/rulego/main/server/deploy/docker/docker-compose.yml -o docker-compose.yml
docker compose up -d

Kubernetes — Helm chart (oci://ghcr.io/rulego/charts/rulego-server) or the single-file manifest attached to each release:

kubectl apply -f rulego-server-all-in-one.yaml   # download from Releases
# or
helm install rulego-server oci://ghcr.io/rulego/charts/rulego-server

Note: the embedded store (bbolt) is single-writer — the chart pins 1 replica with a Recreate strategy.

Linux bare metal — downloads the release archive, installs to /opt/rulego-server, creates a rulego system user and a hardened systemd unit:

curl -fsSL https://raw.githubusercontent.com/rulego/rulego/main/server/deploy/install.sh | bash

Visual Editor

RuleGo-Editor is the visual UI for RuleGo-Server, allowing visual management, debugging and deployment of rule chains.

The web UI is compiled into the binary via go:embed — no extra download or extraction needed, and it does not depend on the working directory at startup:

  • Download and extract the archive for your platform from Release
  • Start the server and open http://localhost:9090/ (Console) or http://localhost:9090/editor/ (standalone editor)

Building from source

The frontend source lives in a separate repository and is not part of this repo. A missing frontend does not break the build — placeholder files under server/webui/ keep go build working; the binary simply ships without a bundled UI, and behavior falls back to:

  • Root path / redirects to /editor/
  • /editor/ is served from disk via resource_mapping in config.conf (default ./editor)

So when building from source, place the frontend build output in an editor folder next to the binary to get the UI (same as older versions).

In binaries with a bundled UI, embed takes precedence over resource_mapping. When both are absent, /editor/ returns 404.

Configuration

  • resource_mapping in config.conf: change the on-disk UI directory (only applies when no UI is bundled)
  • baseUrl in editor/config/config.js: change the backend API address

Public API Packages

Package Import Path Purpose
app github.com/rulego/rulego/server/app App lifecycle, Container, Module interface
bootstrap github.com/rulego/rulego/server/bootstrap Default module assembly (DefaultModules)
bridge github.com/rulego/rulego/server/bridge Host system bridge layer (Gin/Echo etc.)
config github.com/rulego/rulego/server/config Config struct, Load()
model github.com/rulego/rulego/server/model Pure data models
services github.com/rulego/rulego/server/services Stable service interfaces exported by modules
store github.com/rulego/rulego/server/store Storage interfaces
components github.com/rulego/rulego/server/cmd/server Component registration (side-effect import, enabled via build tag)

Component Aggregation Packages

Enabled via build tags. See cmd/server/with_*.go for specific imports:

Build Tag Included Components
with_all All optional components (equivalent to enabling all tags below)
with_ai Agent, LLM, four-primitive tools, etc.
with_iot OPC UA, Modbus, Serial, etc.
with_etl Data transformation components
with_ci CI/CD components
with_extend Kafka, NATS, Redis, Lua, etc.

Application Options

app.New() supports the following functional options:

Option Description
WithConfigFile(path) Configuration file path
WithModules(m...) Add modules
WithModuleOverride(m) Replace a registered module by name
WithStoreProvider(p) Inject a custom store provider (replaces default file storage)
WithHooks(h...) Add lifecycle hooks
WithGlobal(props) Inject global config, merged with [global] section from config file (injected values override file values)
WithTypesLogger(l) Inject a custom logger (Zap, Logrus, etc.)
WithTransportDisabled() Disable default transport layer (embedded mode)
WithoutAutoMkdir() Disable auto-creation of data directories during Init

Custom Development

Custom Module

Implement the app.Module interface and inject via WithModules():

type MyModule struct{}

func (m *MyModule) Name() string     { return "my_module" }
func (m *MyModule) Priority() int    { return 50 }
func (m *MyModule) Init(ctx *app.ModuleContext) error {
    // Register services into the container
    ctx.Container.Register("module.my_module.service", &MyService{})
    return nil
}
func (m *MyModule) Start(ctx context.Context) error { return nil }
func (m *MyModule) Stop(ctx context.Context) error  { return nil }

// Usage
application, _ := app.New(
    app.WithConfigFile("config.conf"),
    app.WithModules(append(bootstrap.DefaultModules(), &MyModule{})...),
)

Replace a built-in module using WithModuleOverride() (e.g., replace the default rule module):

application, _ := app.New(
    app.WithConfigFile("config.conf"),
    app.WithModules(bootstrap.DefaultModules()...),
    app.WithModuleOverride(&MyRuleModule{}),  // replaces module with Name() == "rule"
)

Custom Storage

Implement the store.StoreProvider interface and inject via WithStoreProvider():

application, _ := app.New(
    app.WithConfigFile("config.conf"),
    app.WithStoreProvider(&MyDbStoreProvider{db: myDb}),
    app.WithModules(bootstrap.DefaultModules()...),
)

Interfaces to implement:

Interface Purpose
RuleStore Rule chain CRUD
UserStore User management
SettingStore User settings
RunLogStore Run logs
ComponentStore Component definitions
NodePoolStore Node pool
StoreProvider Factory interface, creates per-user Store instances

Custom Auth

Replace Authenticator or Authorizer via the container:

// Replace in Module.Init
func (m *MyModule) Init(ctx *app.ModuleContext) error {
    ctx.Container.Replace(services.KeyAuthenticator, &OAuth2Authenticator{})
    ctx.Container.Replace(services.KeyAuthorizer, &RBACAuthorizer{})
    return nil
}

Lifecycle Hooks

Insert logic at 5 lifecycle phases via WithHooks():

application, _ := app.New(
    app.WithConfigFile("config.conf"),
    app.WithModules(bootstrap.DefaultModules()...),
    app.WithHooks(
        app.NewFuncHook("my_hook", app.AfterStart, 0,
            func(ctx context.Context, appCtx *app.ModuleContext) error {
                // Post-start initialization logic
                return nil
            },
        ),
    ),
)

Phases: BeforeInit → AfterInit → BeforeStart → AfterStart → OnStop

Module Service Interfaces

Access stable interfaces exported by modules through the Container:

// Rule chain catalog service
catalog := app.MustGetAs[services.ChainCatalog](container, services.KeyRuleCatalog)

// Rule chain executor
executor := app.MustGetAs[services.ChainExecutor](container, services.KeyRuleExecutor)

// Rule chain admin service
admin := app.MustGetAs[services.RuleAdminService](container, services.KeyRuleManager)

Full service list:

Container Key Interface Purpose
module.rule.catalog ChainCatalog Rule chain catalog (read-only)
module.rule.executor ChainExecutor Execute rule chains
module.rule.manager RuleAdminService Rule chain admin (CRUD + deploy)
module.rule.engine_manager EngineManager Multi-tenant engine pool
module.node.service NodeService Component + node pool operations
module.runlog.service RunLogService Run logs
module.locale.service LocaleService Internationalization
module.marketplace.service MarketplaceService Marketplace
module.mcp.service McpService MCP protocol service
module.system.settings ConfigService System configuration
module.user.auth AuthService Password/API Key authentication
module.user.profile UserReader User info reading
module.user.authenticator Authenticator Identity authentication (replaceable, default JWT)
module.user.authorizer Authorizer Authorization (replaceable, default allow-all)
module.skill.service SkillService AI skill management
module.debug.service DebugService Debug service

Configuration

# Basic configuration
data_dir = ./data
server = :9090
default_username = admin

# MCP service configuration
[mcp]
enable = true
# Default endpoint always exposes management API tools; components and chains via groups only

# MCP tool group configuration
[mcp.groups]
manager = preview_rule_chain,save_rule_chain,list_rule_chains,get_rule_chain,delete_rule_chain,operate_rule_chain,execute_rule_chain,list_components,get_component_doc

[global]
# Global variables, accessible in rule chains via ${global.xxx}
llm_url = https://api.openai.com/v1
llm_api_key = ${OPENAI_API_KEY}
llm_model = gpt-4

Multi-instance deployments (cross-replica dedup and single-active endpoints) are enabled by the embedding host injecting a distributed Locker programmatically — standalone file-storage deployments are single-instance by design. See Distributed Deployment.

Managing Rule Chains via Natural Language (MCP)

RuleGo Server includes a built-in MCP (Model Context Protocol) service that allows AI agents to generate, modify, and manage rule chains through natural language. For detailed configuration and AI IDE integration, see the MCP documentation.

MCP Tool List

Tool Name Description
list_rule_chains List/search rule chains
get_rule_chain Get rule chain definition JSON
preview_rule_chain Preview rule chain (validate + return JSON, no save)
save_rule_chain Create or update rule chain (save + deploy)
delete_rule_chain Delete a rule chain
operate_rule_chain Operate rule chain (deploy/undeploy)
execute_rule_chain Execute rule chain and return result
list_components List available components
get_component_doc Get full component documentation
list_node_pool List shared node pool resources

MCP Tool Types

The default MCP endpoint always exposes management API tools (rule chain CRUD, component query, etc.). Components and rule chains are exposed only through group configuration:

Group keyword Description
rules Management API tools (always loaded in default endpoint)
components Expose each registered component as an MCP tool; tool name is component type, description from ComponentForm.Desc
chains Expose each deployed rule chain as an MCP tool; tool name is chain ID, description from additionalInfo.description, falls back to Name

Built-in Agent

RuleGo Server includes a built-in _assistant agent, automatically deployed to data/system/agents/_assistant/ at startup (requires AI components loaded via build tag). Enable it by configuring an LLM:

[global]
llm_url = https://api.openai.com/v1
llm_api_key = ${OPENAI_API_KEY}
llm_model = gpt-4