Prerequisites

.NET 8.0 SDK or later
Operating system: Windows, Linux, or macOS
Git (for cloning the repository)
Elevated privileges (only if listening on all network interfaces)

Building from Source

1. Clone the Repository

git clone https://github.com/jchristn/LiteGraph.git
cd LiteGraph/src

2. Build the Server Project

dotnet build LiteGraph.Server/LiteGraph.Server.csproj

For a release build with optimizations:

dotnet build LiteGraph.Server/LiteGraph.Server.csproj -c Release

3. Navigate to the Output Directory

Debug build:

cd LiteGraph.Server/bin/Debug/net8.0

Release build:

cd LiteGraph.Server/bin/Release/net8.0

Running the Server

Quick Start

dotnet LiteGraph.Server.dll

You should see the LiteGraph logo and startup messages:

  _ _ _                          _
 | (_) |_ ___ __ _ _ _ __ _ _ __| |_
 | | |  _/ -_) _` | '_/ _` | '_ \ ' \
 |_|_|\__\___\__, |_| \__,_| .__/_||_|
             |___/         |_|

 LiteGraph Server
 (c)2025 Joel Christner

Using settings file './litegraph.json'
Settings file './litegraph.json' does not exist, creating
Initializing logging
| syslog://127.0.0.1:514
Creating default records in database litegraph.db
| Created tenant     : 00000000-0000-0000-0000-000000000000
| Created user       : 00000000-0000-0000-0000-000000000000 email: default@user.com pass: password
| Created credential : 00000000-0000-0000-0000-000000000000 bearer token: default
| Created graph      : 00000000-0000-0000-0000-000000000000 Default graph
Finished creating default records
Starting REST server on http://localhost:8701/

Alternative: Run Directly from Project

You can also run without explicitly building first:

cd LiteGraph.Server
dotnet run

For release mode:

dotnet run -c Release

Initial Setup

On first run, LiteGraph Server will automatically:

Create a configuration file (litegraph.json) with default settings
Create a database file (litegraph.db)
Generate default records including:
- Default tenant (GUID: 00000000-0000-0000-0000-000000000000)
- Default user (email: default@user.com, password: password)
- Default credential (bearer token: default)
- Default graph (GUID: 00000000-0000-0000-0000-000000000000)

Configuration

Configuration File

The litegraph.json file controls all server settings. Key configurations include:

Server Settings

{
  "Rest": {
    "Hostname": "localhost",  // Change to "*" or "0.0.0.0" for external access
    "Port": 8701              // Default port
  }
}

Database Settings

{
  "LiteGraph": {
    "AdminBearerToken": "litegraphadmin",  // Admin authentication token
    "GraphRepositoryFilename": "litegraph.db",  // Database file
    "InMemory": false  // Set to true for in-memory operation
  }
}

Logging Settings

{
  "Logging": {
    "ConsoleLogging": true,
    "LogDirectory": "./logs/",
    "LogFilename": "litegraph.log"
  }
}

Command Line Options

Custom Configuration File

Use a different configuration file:

dotnet LiteGraph.Server.dll --config=/path/to/config.json

Environment Variables

The server checks for these environment variables on startup:

LITEGRAPH_PORT - Override the REST API port (must be 0-65535)
LITEGRAPH_DB - Override the database filename

Example:

export LITEGRAPH_PORT=9000
export LITEGRAPH_DB=mydata.db
dotnet LiteGraph.Server.dll

Network Access

Local Access Only (Default)

By default, the server listens on localhost:8701 and is only accessible from the local machine.

External Access

To allow external connections:

Edit litegraph.json:

{
  "Rest": {
    "Hostname": "*"  // or "0.0.0.0" or specific IP
  }
}

Run with elevated privileges (required for wildcard hostname):
- Windows: Run as Administrator
- Linux/macOS: Use sudo
```
sudo dotnet LiteGraph.Server.dll
```

Authentication

LiteGraph Server supports three authentication methods:

1. Administrator Bearer Token

Use the admin token defined in litegraph.json for administrative APIs:

curl -H "Authorization: Bearer litegraphadmin" http://localhost:8701/v1.0/tenants

2. User Credentials

Use email, password, and tenant GUID:

curl -H "x-email: default@user.com" \
     -H "x-password: password" \
     -H "x-tenant-guid: 00000000-0000-0000-0000-000000000000" \
     http://localhost:8701/v1.0/tenants/00000000-0000-0000-0000-000000000000/graphs

3. Security Token

Generate a temporal token (valid for 24 hours):

curl -H "x-email: default@user.com" \
     -H "x-password: password" \
     -H "x-tenant-guid: 00000000-0000-0000-0000-000000000000" \
     http://localhost:8701/v1.0/token

Then use the token:

curl -H "x-token: [generated-token]" http://localhost:8701/v1.0/tenants/00000000-0000-0000-0000-000000000000/graphs

Testing the Server

Check Server Status

curl -I http://localhost:8701/

Get All Graphs (with authentication)

curl -H "Authorization: Bearer default" \
     http://localhost:8701/v1.0/tenants/00000000-0000-0000-0000-000000000000/graphs

curl -X POST -H "Authorization: Bearer litegraphadmin" \
     http://localhost:8701/v1.0/flush

Troubleshooting

Build Errors

Ensure .NET 8.0 SDK is installed: dotnet --version
Restore NuGet packages: dotnet restore
Clean and rebuild: dotnet clean then dotnet build

Server Won't Start

Check if port 8701 is already in use: netstat -an | grep 8701
Verify file permissions for database and log directories
Check for configuration file syntax errors

Cannot Access from External Machine

Ensure Hostname is not set to localhost in configuration
Check firewall settings for port 8701
Verify the server is running with appropriate privileges
Test with telnet: telnet [server-ip] 8701

Authentication Failures

Verify bearer token matches configuration
Check user credentials are correct
Ensure tenant GUID exists
Review authentication headers are properly formatted

Database Issues

Check database file permissions
Verify disk space availability
For in-memory mode, ensure sufficient RAM
Check database file isn't corrupted

Stopping the Server

Press Ctrl+C to gracefully shut down the server.

Important: If running in-memory mode, ensure you flush data to disk before stopping:

curl -X POST -H "Authorization: Bearer litegraphadmin" http://localhost:8701/v1.0/flush