Skip to content

Latest commit

 

History

History
375 lines (265 loc) · 9.81 KB

getting-started-linux.md

File metadata and controls

375 lines (265 loc) · 9.81 KB

Getting Started with ORMCP Server on Linux

Platform-specific guide — This page consolidates all Linux instructions in one place. For the complete multi-platform reference, see the main README.

Prerequisites

  • Python 3.12+ — Check your version: python3 --version
  • Docker — Required for the Gilhari microservice. Get Docker if not already installed.
  • JDBC driver for your target database (bundled in the Gilhari SDK)

Docker Post-Install: Add Your User to the docker Group

On Linux, Docker commands require sudo by default. To run them without it (recommended):

sudo usermod -aG docker $USER

# Log out and back in for the change to take effect, then verify:
docker run hello-world

If you skip this step, prefix all docker commands in this guide with sudo.

Step 1: Install ORMCP Server

Recommended: Virtual Environment

Using a virtual environment is strongly recommended on Linux. Modern distributions (Ubuntu 23.04+, Debian 12+, Fedora 38+, and others) enforce PEP 668 and will block global pip install with an "externally-managed-environment" error. A virtual environment avoids this entirely.

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install ORMCP Server (Beta — replace YOUR_TOKEN with your beta access token)
# Note: --extra-index-url is required because build dependencies (like hatchling)
# are available on PyPI but not on Gemfury
pip install --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server

# Verify installation
pip show ormcp-server

Request your beta access token at softwaretree.com/products/ormcp.

Production (after beta): pip install ormcp-server

Global Installation (Optional)

If you prefer a global install, the ormcp-server executable will be placed in ~/.local/bin/. If the command is not found after installation, add it to your PATH (see Troubleshooting below).

pip install --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server

Note: On distributions that enforce PEP 668, global pip installs will fail with an "externally-managed-environment" error even with sudo. Use a virtual environment instead, or pass --break-system-packages as a last resort (not recommended for production).

Step 2: Set Up the Gilhari Microservice

ORMCP Server depends on Gilhari, a microservice that handles the ORM and database communication. You must have it running before starting ORMCP.

Pull the Gilhari Docker Image

docker pull softwaretree/gilhari:latest

Run the Example Microservice (Quickest Path)

A ready-to-use example microservice is available in a separate repository:

# Clone the example (manages User objects against a SQLite database)
git clone https://github.com/SoftwareTree/gilhari_example1.git
cd gilhari_example1

# Make the scripts executable (required on Linux)
chmod +x *.sh

# Build the Docker image
./build.sh

# Run the microservice (listens on port 80)
docker run -p 80:8081 gilhari_example1:1.0

# (Optional) Populate the database with sample data
./curlCommandsPopulate.sh

Build Your Own Gilhari Microservice

To connect ORMCP to your own database and data model, follow the Gilhari SDK documentation included in the ORMCP source distribution:

# Download the source distribution to access the full SDK
pip download --no-binary :all: \
  --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server

# Extract it
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

# The Gilhari SDK is in:
# - Gilhari_SDK/          (documentation, tools, sample apps)
# - gilhari_example1/     (example microservice)

Step 3: Configure Environment Variables

Set these variables in your terminal before starting ORMCP Server. For the example microservice running on port 80:

export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
export MCP_SERVER_NAME="MyORMCPServer"

All available configuration variables:

Variable Description Default
GILHARI_BASE_URL Gilhari microservice URL http://localhost:80/gilhari/v1/
MCP_SERVER_NAME Server identifier ORMCPServerDemo
GILHARI_TIMEOUT API timeout in seconds 30
LOG_LEVEL Logging verbosity INFO
READONLY_MODE Expose only read operations False
GILHARI_NAME Name of the Gilhari container ""
GILHARI_IMAGE Docker image for Gilhari ""
GILHARI_HOST Host IP for Gilhari localhost
GILHARI_PORT Port for Gilhari 80

To make these variables permanent, add the export lines to your ~/.bashrc (most Linux distros) or ~/.zshrc (if using zsh):

# Add to ~/.bashrc
export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
export MCP_SERVER_NAME="MyORMCPServer"

# Reload your shell
source ~/.bashrc

Step 4: Start ORMCP Server

If you are using a virtual environment, activate it first:

source .venv/bin/activate

Then start the server:

ormcp-server

Expected output:

[INFO] ORMCP server name: MyORMCPServer
[INFO] GILHARI BASE URL: http://localhost:80/gilhari/v1/
[INFO] ORMCP server v0.5.x starting in stdio mode ...

Alternative Start Methods

# Using the full path (if not in PATH)
~/.local/bin/ormcp-server

# Using Python directly (always works)
python3 -m ormcp_server

# HTTP mode (experimental)
ormcp-server --mode http --port 8080

Step 5: Connect Your AI Client

Claude Desktop

Locate or create your Claude Desktop config file at:

~/.config/Claude/claude_desktop_config.json

Create the directory if it doesn't exist:

mkdir -p ~/.config/Claude

Option 1: Using the command name (virtual environment)

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "/path/to/.venv/bin/ormcp-server",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Option 2: Using the command name (global install)

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "ormcp-server",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Option 3: Using Python directly

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "python3",
      "args": ["-m", "ormcp_server"],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

To find the exact path to your ormcp-server executable:

which ormcp-server
# or
pip show -f ormcp-server | grep "ormcp-server$"

Note: When using Claude Desktop, steps 3 and 4 above (setting environment variables and manually starting the server) are not necessary — Claude Desktop automatically starts the ORMCP server in STDIO mode using the config above.

Gemini CLI

Add to your Gemini settings.json. Note that Gemini CLI currently requires HTTP mode, so start ORMCP with --mode http first:

{
  "mcpServers": {
    "my-ormcp-server-http": {
      "httpUrl": "http://127.0.0.1:8080/mcp"
    }
  }
}

OpenAI GPTs (Developer Mode)

The ORMCP server must be running in HTTP mode and accessible via a public URL. See the main README for the full walkthrough using cloudflared or ngrok.

Other MCP Clients

Configure using the appropriate transport (STDIO or HTTP) per your client's requirements. See:

Troubleshooting

command not found: ormcp-server

The executable is installed to ~/.local/bin/ but that directory may not be in your PATH. Add it:

# Add to ~/.bashrc (or ~/.zshrc if using zsh)
export PATH="$HOME/.local/bin:$PATH"

# Reload
source ~/.bashrc

Or use the full path directly:

~/.local/bin/ormcp-server

"Externally managed environment" error

This is common on Ubuntu 23.04+, Debian 12+, Fedora 38+, and other distributions that enforce PEP 668. The fix is to use a virtual environment as shown in Step 1:

python3 -m venv .venv
source .venv/bin/activate
pip install ...

For more detail, see the Complete Troubleshooting Guide.

Docker permission denied

If you see permission denied while trying to connect to the Docker daemon socket, your user is not in the docker group:

sudo usermod -aG docker $USER
# Log out and back in, then retry

Shell script permission denied

If ./build.sh is not executable:

chmod +x *.sh
./build.sh

Enable debug logging

export LOG_LEVEL=DEBUG
ormcp-server

Server won't start

Verify Gilhari is running and accessible:

curl -i http://localhost:80/gilhari/v1/getObjectModelSummary/now

For more, see the Complete Troubleshooting Guide.

Resources