Configuration

Complete reference for xyOps server configuration options, override layers, and environment variables

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:

1. Base Configuration

   Primary configuration file:

   /opt/xyops/conf/config.json
   

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

2. 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": "[e-mail]",
    "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:

Shell

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.

References

• pixl-server-storage Documentation
• pixl-server-web Documentation
• Nodemailer SMTP Configuration
• System Hooks