(xcserver)=

# Host Administration

## 1. Configuration

XCOMPUTE-SERVER ingests several configuration files at launch. Edit these files to customize behavior, access control, and compute defaults.

### Host Setup (`server.cfg`)
Define one or two administrators. The first must match the email/fingerprint used for the server license. The optional second should be a trusted deputy.

    admin=tech.boss@company.com          # Required: Registered server email
    fingerprint=YOUR_XCSERVER_FINGERPRINT # Required: Server license fingerprint
    admin2=tech.deputy@company.com       # Optional: Trusted client email (must be in users.cfg)
    input=/mnt/FAST_SSD/                 # Project load directory
    output=/mnt/FAST_SSD/                # Project save directory
    cache=/mnt/FAST_SSD/_cache/          # Temporary runtime files (underscore prefix recommended)

> **Tip**: For enhanced isolation and performance, consider mounting `cache` on a separate high-speed drive.

Server administration is typically performed headless via SSH. Administrators act on behalf of their organization and have full access to project data. Exercise caution; mismanagement can corrupt or destroy projects. Contact Xplicit Computing for administrative support.

### User Access (`users.cfg`)
Manage team access by adding fingerprints and emails:

    allow_guests=false
    SOMEONES_XCCLIENT_FINGERPRINT=someone@somewhere.com
    ANOTHERS_XCCLIENT_FINGERPRINT=helper@subcontractor.com

Set `allow_guests=true` to permit read-only public access. Default is `false`.

### Host Collaboration (`hosts.cfg`)
Configure LAN auto-discovery and remote server connections:

    # localnet=192.168.1   # Optional: Class-C subnet scan range
    CLUSTER_XCSERVER_FINGERPRINT=192.168.1.2
    ANOTHER_XCSERVER_FINGERPRINT=anothercompany.com

> Server-to-server protocols and load distribution are under active development.

### Compute Defaults (`compute.cfg`)
Set preferred default solver and meshing parameters:

    ReservedThreads=1       # CPU threads reserved for server responsiveness
    DefaultDevice=0         # 0: Auto-select best OpenCL device
    Iterations=500          # Default steps for iterative solvers
    Resolution=16000000     # Shape resolution (typically 1e6–1e8)
    ElementCount=40000      # Default node/cell count for new meshes

## 2. Execution Modes

### System-Managed Service (Recommended)
XCOMPUTE-SERVER can run as a persistent `systemd` service, starting automatically on boot.

**Installation**: Use the Debian (`.deb`) package. Requires `root` privileges. Creates a dedicated `xcompute` system user.

**Service Management**:
    # Check status
    systemctl status xcompute

    # Start / Stop / Restart
    sudo systemctl start xcompute
    sudo systemctl stop xcompute
    sudo systemctl restart xcompute

**Expected Output**:

    ● xcompute.service - XCOMPUTE Service
         Loaded: loaded (/etc/systemd/system/xcompute.service; linked; vendor preset: enabled)
         Active: active (running) since Sat 2025-03-29 18:32:35 PDT; 18min ago
       Main PID: 233561 (xcompute-server)
          Tasks: 13 (limit: 18988)
         Memory: 21.4M
         CGroup: /system.slice/xcompute.service
                 └─233561 /opt/xcompute/xcserver/bin/xcompute-server

Logs are written to `/var/opt/xcompute/xcserver/log/`:
- `xcserver.log`: Standard output (version, license, CPU/OpenCL detection)
- `xcserver.err`: Errors and warnings

**Example Startup Log**:

    Model name:                           Intel(R) Core(TM) i9-9900 CPU @ 3.10GHz
    CPU(s):                               16
    NUMA node0 CPU(s):                    0-15
    ...
    compute platform: NVIDIA CUDA
    OpenCL 3.0 CUDA 12.4.131 (FULL_PROFILE)
    ...

### User-Managed Execution
Run manually without `root` privileges. Suitable for individual use or environments where system services are restricted.

    ./xcompute-server

Ensure the listening socket binds successfully and at least one OpenCL device is detected. Only one instance can run at a time.

## 3. File I/O & Storage

| Operation | Server Side | Client Side |
|-----------|-------------|-------------|
| **Input** | Load from host filesystem | Import from local machine |
| **Output** | Save to host filesystem | Export to local machine |

### Save & Load
- **Save**: Writes project state to the `output` directory.
- **Load**: Reads from the `input` directory.
- Each system maps to a folder containing:
  - `*.xcs` / `*.json`: System setup (JSON tried first, then XCS)
  - `*.xcg`: Native geometry
  - `*.xco`: Data properties (view with `xc2csv` or XC-Messages bindings)
- Previous states are backed up with a `.` prefix for triple-redundancy.

### Import & Export
Files are staged in the `cache` directory during transfer to prevent corruption. Supported formats:
- **Import**: `stl`, `obj`, `msh`, `sdf`
- **Export**: `csv`, `vtu`, `stl`, `obj`, `msh`, `sdf`

Default export types can be set in `compute.cfg`:
    SystemExportType=vtu
    GeometryExportType=msh

## 4. Troubleshooting

### Common Errors
**Authentication Failed**:

    Cannot authenticate without a fingerprint. Aborting.
    Authentication Failed.
    A valid certificate is required to launch xcompute-server...

**Fix**: Verify `fingerprint` in `server.cfg` matches your license. Check certificate validity in your account profile.

### Log Inspection

Review logs for OpenCL device detection, license loading, and network binding status.

    # View standard logs
    vi /var/opt/xcompute/xcserver/log/xcserver.log

    # View errors
    vi /var/opt/xcompute/xcserver/log/xcserver.err