SOTER Sysadmin & Operations Manual — Installation & Control

Audience

DevOps engineers, sysadmins, and installation specialists responsible for installing, configuring, and operating SOTER.

Goal

Install SOTER, configure the tenant/model configuration cascade correctly, run it safely in production Protected Mode, and manage the server daemon, logs, and databases.

Prerequisites

• Python 3.12+ and standard system dependencies.
• Shell access to run the soter CLI wrapper.
• Understanding of the multi-tenant isolation rule: tenant-level soter.conf files are strictly forbidden; all local settings must reside in JSON files.

Workflow

1. Clone the repository and set up an isolated Python environment.
2. Install the package in editable development mode.
3. Understand the configuration priority cascade before changing settings, from most global to most specific:
4. Global Configuration (soter.conf — TOML): root-level installation fallback handling devops/server boundaries.
5. Tenant Configuration (soter.json — JSON): workspace configuration declaring tenant parameters.
6. Model Configuration (model.json — JSON): schema-specific settings.
7. View Configuration (.view — JSON headers): viewport parameters.
8. When deploying to production, set SOTER_ENV=production so the Epiphany portal runs in Protected Mode:
9. Mandatory authentication is enforced for all paths except the public / README screen.
10. Global and tenant configuration forms in the UI are hidden or locked.
11. Graph databases are kept read-only.
12. Manage the server daemon lifecycle with the CLI commands below.
13. Monitor runtime logs and the recompiled databases to confirm the system is healthy.

Commands

Sandbox setup:

# Clone and enter the repository
cd 1_soter

# Initialize python virtual environment
python -m venv .venv
source .venv/bin/activate

# Install package in editable development mode
pip install -e ".[dev]"

CLI lifecycle management:

soter server start         # Start server in background
soter server start --live  # Run and tail logs interactively
soter server stop          # Stop server & free port :8000
soter server stop --all    # Stop everything including docker containers
soter server status        # Query PID & active ports
soter server logs --follow # Tail system logs dynamically
soter diagnose             # Run diagnostic environment scan

Expected Result

The virtual environment activates and pip install -e ".[dev]" completes without error. Configuration resolves in the documented cascade order, with no tenant-level soter.conf present. In production, the portal enforces authentication everywhere except the public / screen and keeps configuration forms and graph databases locked/read-only. soter server status reports the running PID and active ports, and the SQLite index (out/<model>.sqlite3) and KuzuDB graph (out/kuzu/) are recompiled on every schema build.

Troubleshooting

A tenant defines its own soter.conf

Cause:

• Tenant-level soter.conf (TOML) files are forbidden under the multi-tenant isolation rule.

Fix:

• Move the settings into the appropriate JSON file (soter.json for tenant configuration, model.json for schema-specific settings).

Server will not stop or a port stays occupied

Cause:

• A related process (including a docker container) is still bound to the port.

Fix:

• Run soter server stop --all to stop everything, including docker containers, instead of a plain soter server stop.

Unclear why the environment is misbehaving

Cause:

• Environment, dependency, or configuration issues that are not obvious from the logs alone.

Fix:

• Run soter diagnose to get a diagnostic environment scan, and check log/epiphany.log or soter.log for runtime errors.

Related Documents

• DocumentationStyleGuide.md - writing profile and document-type rules.
• GuideTemplate.md - guide document template.
• ManualsIndex.md - guide and manual index.
• ArchitectureOverview.md - technical architecture context.