Running the Server
ordo-server runs rules for your applications. It serves HTTP on port 8080 and gRPC on port 50051, and can also listen on a Unix socket.
Start it
With Docker:
docker run -p 8080:8080 -p 50051:50051 ghcr.io/ordo-engine/ordo:latest
curl http://localhost:8080/healthFrom source (Rust 1.83 or later):
git clone https://github.com/Ordo-Engine/Ordo.git && cd Ordo
cargo build --release
./target/release/ordo-server --rules-dir ./rulesEvery flag also has an ORDO_* environment variable. See Server Options.
Keep rules on disk
Without --rules-dir, rules live in memory and are gone after a restart. With it:
.json,.yamland.ymlfiles in the folder are loaded at startup. The file name is the rule name.- Rules created, updated or deleted through the API are written to the folder.
- A write-ahead log in
<rules-dir>/wal/makes writes crash safe.
docker run -p 8080:8080 -v "$PWD/rules:/data/rules" --user "$(id -u):$(id -g)" \
ghcr.io/ordo-engine/ordo:latest --rules-dir /data/rulesThe folder must be writable from inside the container. On Linux, --user runs the container as you so it can write to your folder.
To pick up files that change on disk (from git or a deploy script), add --watch-rules. To reload by hand, call POST /api/v1/admin/reload.
Call a rule
curl -X POST http://localhost:8080/api/v1/rulesets \
-H 'Content-Type: application/json' -d @rulesets/discount.json
curl -X POST http://localhost:8080/api/v1/execute/discount \
-H 'Content-Type: application/json' \
-d '{"input":{"user":{"tier":"gold"},"order":{"amount":1200}}}'{ "code": "OK", "message": "", "output": { "rate": 0.15, "pay": 1020.0 }, "duration_us": 12 }Add "trace": true to see the path. For many inputs at once, use POST /api/v1/execute/discount/batch with {"inputs": [...]}. The HTTP API and gRPC API list everything.
Client libraries for Go, Python and Java are in sdk/ in the repository. They are not on the package registries yet.
External data
Rules can read lookup tables and limits that change without a rule edit, such as a price list or a country risk table. The server keeps them as named JSON values and passes them to every rule as $data:
curl -X PUT http://localhost:8080/api/v1/data/limits \
-H 'Content-Type: application/json' -d '{"vip_min": 1000, "eu_rate": 0.2}'A rule then uses $data.limits.vip_min like any field, for example order.amount >= $data.limits.vip_min. The next request sees the new value.
With --rules-dir, values are saved to <rules-dir>/data/<name>.json, and .json, .yaml or .yml files placed there are loaded at startup. With tenants, each tenant has its own data in <rules-dir>/tenants/<id>/data/. GET /api/v1/data lists the names. On the command line, ordo exec --data limits.json does the same for one run.
Versions and rollback
With --rules-dir, each update keeps the previous version next to the rule file (discount.v1.json, discount.v2.json, …). --max-versions (default 10) sets how many are kept.
curl http://localhost:8080/api/v1/rulesets/discount/versions
curl -X POST http://localhost:8080/api/v1/rulesets/discount/rollback \
-H 'Content-Type: application/json' -d '{"seq": 1}'{ "status": "rolled_back", "name": "discount", "from_version": "1.1.0", "to_version": "1.0.0" }Without --rules-dir there is no history and rollback returns an error.
Health checks
| Endpoint | Use |
|---|---|
/healthz/live | Liveness: 200 while the process runs |
/healthz/ready | Readiness: checks the rule store and that --rules-dir is writable |
/health | Same as /healthz/ready |
/metrics | Prometheus metrics. See Metrics |
These are never behind the API token or the concurrency limit.
Audit log
Rule changes and a sample of executions are written as JSON lines to stdout, and to daily files when --audit-dir is set:
ordo-server --rules-dir ./rules --audit-dir ./audit --audit-sample-rate 10{"timestamp":"…","level":"INFO","event":"rule_updated","rule_name":"discount","from_version":"1.0.0","to_version":"1.1.0","source_ip":"127.0.0.1"}Events: server_started, server_stopped, rule_created, rule_updated, rule_deleted, rule_rollback, rule_executed (sampled) and sample_rate_changed. --audit-sample-rate is a percentage of executions, default 10. Change it at runtime with PUT /api/v1/config/audit-sample-rate and {"sample_rate": 50}.
Access
Ordo is meant for internal networks, so nothing is locked by default. What you can turn on:
--api-token <secret>: data routes needAuthorization: Bearer <secret>orX-API-Token: <secret>.--cors-allowed-origins: allow a browser app (such as Studio) on another origin.--grpc-tls-certand--grpc-tls-keyfor gRPC TLS,--grpc-mtls-enabledfor client certificates. For HTTPS, put a proxy in front.--max-concurrent-executions,--request-timeout-secs,--max-request-body-bytesto limit load.
Tenants
With --multi-tenancy-enabled, every request names a tenant in the X-Tenant-ID header (gRPC: x-tenant-id metadata). Each tenant has its own rules, stored under <rules-dir>/tenants/<id>/, and its own limits:
curl -X POST http://localhost:8080/api/v1/tenants -H 'Content-Type: application/json' \
-d '{"id":"shop-eu","name":"Shop EU","qps_limit":500,"burst_limit":1000,"execution_timeout_ms":50}'Requests without the header use --default-tenant (default default).
Next
- Deployment: several instances, Kubernetes, Nomad, signed rules
- Embedding: run the engine inside a Rust program or a browser