Configuration

xyOps is configured primarily through JSON files with support for UI-based overrides and environment variable substitution.

Configuration Files

xyOps uses a two-layer configuration system:

Base Configuration

Primary configuration file:

/opt/xyops/conf/config.json

This file contains all default settings and is typically version-controlled.

Override Layer

UI modifications are saved to:

/opt/xyops/conf/overrides.json

Settings in this file take precedence over config.json.

The override system allows you to modify settings via the web UI without editing the base config file. Changes persist across upgrades.

Global Settings

Application URLs and Paths

base_app_url

string

default:"http://localhost:5522"

Base URL of your xyOps instance. Used to build fully-qualified links in emails, alerts, tickets, and web hooks.

"base_app_url": "https://xyops.yourcompany.com"

secret_key

string

default:"initial"

Shared secret for signing tokens, authenticating multi-conductor messages, and encrypting stored secrets.

Set this to a long random value in production. Rotate every few months for security.

"secret_key": "your-long-random-secret-here"

temp_dir

string

default:"temp"

Scratch directory for temporary files (plugin bundles, staging uploads). Relative to xyOps base directory.

pid_file

string

default:"logs/xyops.pid"

Path to the main process PID file for start/stop tooling.

Logging Configuration

debug_level

number

default:"5"

Verbosity level for the logger (1 = quiet, 10 = very verbose).

log_dir

string

default:"logs"

Base directory for server logs and job logs. Example: logs/Error.log, logs/jobs/ID.log

log_filename

string

default:"[component].log"

Filename pattern for core logger. Supports column placeholders like [component].

log_columns

array

Controls which log columns are written and their order.

Log Archive Configuration

log_archive_path

string

Nightly log archive path pattern. Supports date/time placeholders.

log_archive_keep

string

default:"30 days"

Retention period for log archives. Empty string keeps indefinitely.

log_archive_storage

object

Archive logs to storage (S3) instead of local disk:

"log_archive_storage": {
  "enabled": true,
  "key_template": "logs/archives/[yyyy]/[mm]/[dd]/[filename]-[yyyy]-[mm]-[dd].log.gz",
  "expiration": "1 year"
}

Timing and Scheduling

tick_precision_ms

number

default:"50"

Internal timer precision in milliseconds. Lower values = more precise execution but higher idle CPU.

maintenance

string

default:"04:00"

Daily maintenance schedule (HH:MM format, server local time) for DB trimming and log archival.

ttl

number

default:"300"

Default HTTP cache TTL (seconds) for API responses and static resources.

WebSocket Settings

ping_freq_sec

number

default:"5"

Interval for sending WebSocket pings to clients/workers (seconds).

ping_timeout_sec

number

default:"30"

Maximum time without pong before socket timeout (seconds).

Job Configuration

max_jobs_per_min

number

default:"100"

Global rate limit on job starts per minute. E-brake mechanism to prevent runaway workflows.

dead_job_timeout

number

default:"120"

Seconds without updates before running job is considered dead and aborted.

job_env

object

default:"{}"

Environment variables merged into every job process. Can be overridden per-job.

"job_env": {
  "PATH": "/usr/local/bin:/usr/bin:/bin",
  "LANG": "en_US.UTF-8"
}

job_universal_actions

object

Global actions executed when conditions are met. Organized by job type:

"job_universal_actions": {
  "default": [
    {
      "enabled": true,
      "hidden": false,
      "condition": "error",
      "type": "snapshot"
    }
  ],
  "workflow": []
}

Email Configuration

email_from

string

default:"admin@localhost"

Sender email address for all outbound messages. Must be valid for most SMTP servers.

mail_settings

object

Email transport configuration passed to Nodemailer.

SMTP Examples

Basic SMTP:

"mail_settings": {
  "host": "localhost",
  "port": 25
}

Authenticated SMTP (Fastmail):

"mail_settings": {
  "host": "smtp.fastmail.com",
  "port": 465,
  "auth": {
    "user": "youremail@fastmail.com",
    "pass": "YOUR_PASSWORD"
  },
  "secure": true
}

Local Sendmail:

"mail_settings": {
  "sendmail": true,
  "newline": "unix",
  "path": "/usr/sbin/sendmail"
}

email_format

string

default:"html"

Email body format: html for styled emails, text for plain text.

email_logo

string

default:"inline"

Logo handling: link (URL to logo), inline (attachment), or none.

max_emails_per_day

number

default:"0"

Daily email cap across the app. 0 = no limit. Excess sends rejected with error.

Alert Configuration

stale_alert_timeout

number

default:"90"

Seconds before stale alerts are cleared (when server disconnects with active alerts).

alert_universal_actions

array

Actions automatically applied to all alerts:

"alert_universal_actions": [
  {
    "enabled": true,
    "hidden": true,
    "condition": "alert_new",
    "type": "snapshot"
  }
]

Display Formatting

hostname_display_strip

string

default:"\\\\.[\\\\w\\\\-]+\\\\.\\\\w+$"

Regex removed from hostname endings for display (strips domain suffix).

ip_display_strip

string

default:"^::ffff:"

Regex removed from IP addresses (strips IPv6 IPv4-mapped prefix).

search_file_regex

string

default:"\\\\.(txt|log|csv|tsv|xml|json)(\\\\.gz)?$"

Limits which filenames are scanned by file search APIs.

Storage Backend

xyOps uses pixl-server-storage for data persistence.

Storage.engine

string

default:"Hybrid"

Storage engine selection. Options: Hybrid, Filesystem, SQLite, S3, Redis.See Storage Engines.

Hybrid Engine Configuration

Combines multiple backends for optimal performance:

"Storage": {
  "engine": "Hybrid",
  "Hybrid": {
    "docEngine": "SQLite",
    "binaryEngine": "Filesystem"
  }
}

Common patterns:

SQLite for JSON + Filesystem for binaries (default)
Redis for JSON + S3 for binaries (multi-conductor)

SQLite Configuration

Storage.SQLite.base_dir

string

default:"data"

Base directory for SQLite database file.

Storage.SQLite.filename

string

default:"sqlite.db"

Database filename.

Storage.SQLite.pragmas

object

SQLite PRAGMA settings:

"pragmas": {
  "auto_vacuum": 0,
  "cache_size": -100000,
  "journal_mode": "WAL"
}

Storage.SQLite.backups

object

Automated backup configuration:

"backups": {
  "enabled": true,
  "dir": "data/backups",
  "filename": "backup-[yyyy]-[mm]-[dd]-[hh]-[mi]-[ss].db",
  "compress": true,
  "keep": 7
}

S3 Configuration

Storage.AWS.region

string

default:"us-west-1"

AWS region for S3 backend.

Storage.AWS.credentials

object

"credentials": {
  "accessKeyId": "YOUR_ACCESS_KEY",
  "secretAccessKey": "YOUR_SECRET_KEY"
}

Storage.S3.params.Bucket

string

S3 bucket name for storage.

See Amazon S3 Engine.

Storage Cache Settings

Storage.{Engine}.cache.enabled

boolean

default:"true"

Enable in-memory caching for storage operations.

Storage.{Engine}.cache.maxBytes

number

default:"104857600"

Maximum cache size in bytes (~100 MB default).

Storage.{Engine}.cache.maxItems

number

default:"100000"

Maximum number of cached items.

Web Server Configuration

xyOps uses pixl-server-web for HTTP/HTTPS.

WebServer.port

number

default:"5522"

HTTP listener port.

WebServer.htdocs_dir

string

default:"htdocs"

Base directory for static assets and web UI.

WebServer.max_upload_size

number

default:"1073741824"

Maximum upload size in bytes (1 GB default).

HTTPS/TLS Configuration

WebServer.https

boolean

default:"true"

Enable HTTPS support.

WebServer.https_port

number

default:"5523"

HTTPS listener port.

WebServer.https_cert_file

string

default:"conf/tls.crt"

TLS certificate file path.

WebServer.https_key_file

string

default:"conf/tls.key"

TLS private key file path.

WebServer.https_force

boolean

default:"false"

Force HTTP to redirect to HTTPS.

Security Settings

WebServer.whitelist

array

default:"[]"

Client IPs/CIDRs explicitly allowed to access the webserver.

"whitelist": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]

WebServer.blacklist

array

default:"[]"

Client IPs/CIDRs explicitly denied.

WebServer.max_connections

number

default:"2048"

Maximum concurrent socket connections.

WebServer.max_concurrent_requests

number

default:"256"

Maximum concurrent requests.

Database Maintenance

Configure retention limits to prevent unbounded growth:

"db_maint": {
  "jobs": { "max_rows": 1000000 },
  "alerts": { "max_rows": 100000 },
  "snapshots": { "max_rows": 100000 },
  "activity": { "max_rows": 100000 },
  "servers": { "max_rows": 10000 }
}

Oldest records are pruned during nightly maintenance.

Environment Variable Overrides

Many configuration options can be overridden via environment variables:

export NODE_MAX_MEMORY=8192
export XYOPS_base_app_url="https://xyops.example.com"
export XYOPS_debug_level=9

Prefix configuration paths with XYOPS_ and use underscores for nested paths.

Get Started

Core Concepts

Monitoring & Alerts

Organization

Operations

Plugins & Extensions

Advanced

Configuration

Configuration Files

Global Settings

Application URLs and Paths

Logging Configuration

Timing and Scheduling

WebSocket Settings

Job Configuration

Email Configuration

Alert Configuration

Display Formatting

Storage Backend

Storage Cache Settings

Web Server Configuration

HTTPS/TLS Configuration

Security Settings

Database Maintenance

Environment Variable Overrides

References

Build docs developers (and LLMs) love

Get Started

Core Concepts

Monitoring & Alerts

Organization

Operations

Plugins & Extensions

Advanced

Documentation Index

​Configuration Files

​Global Settings

​Application URLs and Paths

​Logging Configuration

​Timing and Scheduling

​WebSocket Settings

​Job Configuration

​Email Configuration

​Alert Configuration

​Display Formatting

​Storage Backend

​Storage Cache Settings

​Web Server Configuration

​HTTPS/TLS Configuration

​Security Settings

​Database Maintenance

​Environment Variable Overrides

​References

Build docs developers (and LLMs) love

Configuration Files

Global Settings

Application URLs and Paths

Logging Configuration

Timing and Scheduling

WebSocket Settings

Job Configuration

Email Configuration

Alert Configuration

Display Formatting

Storage Backend

Storage Cache Settings

Web Server Configuration

HTTPS/TLS Configuration

Security Settings

Database Maintenance

Environment Variable Overrides

References