Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pixlcore/xyops/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers setting up xyOps for local development, understanding the architecture, and making contributions.

​
Prerequisites

Before starting, install:
  • Node.js v16 or later (download)
  • Git
  • A code editor

​
Local development setup

1

Clone the repository

git clone https://github.com/pixlcore/xyops.git
cd xyops
2

Install dependencies

npm install
This installs all required Node.js packages including the pixl-server framework and dependencies.
3

Build the client

node bin/build.js dev
This compiles the web UI assets in development mode (unminified).
4

Start in debug mode

bin/debug.sh
This starts xyOps with:
  • Debug logging enabled
  • Console output visible
  • Automatic restart on crashes
  • REPL (read-eval-print loop) for live inspection
Access the UI at http://localhost:5522 (default credentials: admin / admin).

​
Architecture overview

xyOps is built on the pixl-server framework and consists of several key components:

​
Server components

From ~/workspace/source/lib/:
  • main.js - Entry point, loads pixl-server
  • engine.js - Core scheduler and event loop
  • job.js - Job launch and lifecycle management
  • workflow.js - Workflow execution engine
  • schedule.js - Trigger evaluation and scheduling
  • action.js - Action execution (emails, webhooks, etc.)
  • alert.js - Alert evaluation and invocations
  • monitor.js - Time-series metrics collection
  • server.js - Server and worker management
  • ticket.js - Ticketing system
  • multi.js - Multi-conductor coordination
  • api.js - REST API handler

​
API endpoints

From ~/workspace/source/lib/api/:
  • events.js - Event CRUD operations
  • jobs.js - Job monitoring and control
  • servers.js - Server inventory
  • monitors.js - Monitor management
  • alerts.js - Alert definitions
  • tickets.js - Ticket system
  • user.js - User management
  • admin.js - Admin operations

​
Client framework

From ~/workspace/source/htdocs/js/: The web UI is built with:
  • jQuery for DOM manipulation
  • xyApp (pixl-xyapp) for single-page app routing
  • CodeMirror for code editing
  • Chart.js for graphing
  • xterm.js for terminal output

​
Debug mode features

Debug mode (bin/debug.sh) provides:

​
REPL console

Press Enter at the console to access the REPL: 
> server.config.get('port')
5522

> server.Storage.listKeys('events', function(err, keys) { console.log(keys); })

> this.schedule
{ /* scheduler state */ }
The REPL has access to the server object and all loaded components.

​
Live logging

All components log to STDOUT with color-coded levels:
  • Error - Red
  • Warning - Yellow
  • Debug - Gray
  • Traffic - Cyan
Set debug_level in conf/config.json (1-10) to control verbosity.

​
Running tests

xyOps includes a test suite: 
npm test
Tests cover:
  • Event scheduling logic
  • Workflow execution
  • Monitor evaluation
  • Alert conditions
  • Plugin wire protocol
From ~/workspace/source/test/.

​
Generating self-signed certificates

For local HTTPS development: 
openssl req -x509 -newkey rsa:2048 \
  -keyout conf/tls.key \
  -out conf/tls.crt \
  -days 365 -nodes \
  -subj "/CN=localhost"
Then enable HTTPS in conf/config.json: 
{
  "WebServer": {
    "https": true,
    "https_port": 5523,
    "https_cert_file": "conf/tls.crt",
    "https_key_file": "conf/tls.key"
  }
}
Access at https://localhost:5523 (accept the self-signed certificate warning).

​
Code style

Follow these conventions:
  • Indentation: Tabs (width 4)
  • Line length: No hard limit, but prefer < 120 characters
  • Semicolons: Required
  • Quotes: Single quotes for strings
  • Comments: Explain why, not what
Existing code uses a consistent style—match it when contributing.

​
Making changes

1

Create a branch

git checkout -b my-feature-branch
2

Make your changes

Edit files in lib/, htdocs/, or docs/.For UI changes, rebuild with:
node bin/build.js dev
Refresh your browser to see changes.
3

Test your changes

  • Run the test suite: npm test
  • Test manually in the UI
  • Check debug logs for errors
4

Commit and push

git add .
git commit -m "Add feature: description"
git push origin my-feature-branch

​
Contribution guidelines

Before submitting code changes, read our Contributing Guide. TL;DR:
  • We do not accept feature PRs
  • Bug fixes are welcome (open an issue first)
  • Documentation improvements are always appreciated
  • Security issues should be reported privately (see Security)

​
Useful commands

# Start in debug mode
bin/debug.sh

# Start normally (daemon)
bin/control.sh start

# Stop server
bin/control.sh stop

# View logs
tail -f logs/Error.log
tail -f logs/Debug.log

# Rebuild UI (production)
node bin/build.js prod

# Run tests
npm test

# Database CLI
bin/db-cli.js

# Storage CLI
bin/storage-cli.js

# Recover admin access
bin/control.sh recover

​
Project structure

xyops/
├── bin/           # CLI utilities and control scripts
├── conf/          # Configuration files
├── data/          # Storage directory
├── docs/          # Markdown documentation
├── htdocs/        # Web UI static assets
│   ├── css/
│   ├── js/
│   └── images/
├── internal/      # Internal JSON definitions
├── lib/           # Server-side code
│   ├── api/       # API endpoint handlers
│   └── *.js       # Core components
├── logs/          # Log files
├── sample_conf/   # Example configurations
└── test/          # Test suite

​
See also