Add Linux installation guide with all AI agent options
Covers Debian/Ubuntu, Fedora, Arch. Includes: - Gemini CLI (recommended free: 1000 req/day, SSE direct) - Claude Desktop (official Linux beta via apt, stdio) - ChatGPT/Codex CLI (paid only, noted as unavailable on Linux) - Built-in AI Coach (free API keys + Ollama offline) - systemd service for auto-start - venv vs system-wide install options - No tzdata needed (Linux has system timezone DB)
This commit is contained in:
parent
37c152060a
commit
aba8d42123
1 changed files with 444 additions and 0 deletions
444
docs/INSTALL-LINUX.md
Normal file
444
docs/INSTALL-LINUX.md
Normal file
|
|
@ -0,0 +1,444 @@
|
|||
# Diligence Fitness — Linux Installation Guide
|
||||
|
||||
Complete installation from a clean Linux machine with no dependencies.
|
||||
Tested on Ubuntu 22.04+, Debian 12+. Most steps work on any distro with
|
||||
Python 3.10+ and pip.
|
||||
|
||||
---
|
||||
|
||||
## 1. Install Python and pip
|
||||
|
||||
Most Linux distributions include Python 3. Verify:
|
||||
|
||||
```bash
|
||||
python3 --version
|
||||
pip3 --version
|
||||
```
|
||||
|
||||
If pip is missing:
|
||||
|
||||
```bash
|
||||
# Debian/Ubuntu
|
||||
sudo apt update && sudo apt install python3-pip python3-venv unzip curl
|
||||
|
||||
# Fedora
|
||||
sudo dnf install python3-pip python3 unzip curl
|
||||
|
||||
# Arch
|
||||
sudo pacman -S python-pip python unzip curl
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Install Node.js
|
||||
|
||||
Required for Gemini CLI. Skip if you only plan to use the built-in AI Coach
|
||||
(see Section 7d).
|
||||
|
||||
```bash
|
||||
# Debian/Ubuntu (via NodeSource)
|
||||
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
|
||||
sudo apt install -y nodejs
|
||||
|
||||
# Fedora
|
||||
sudo dnf install nodejs
|
||||
|
||||
# Arch
|
||||
sudo pacman -S nodejs npm
|
||||
|
||||
# Or via nvm (any distro)
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
|
||||
source ~/.bashrc
|
||||
nvm install --lts
|
||||
```
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
node --version
|
||||
npm --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Download Diligence
|
||||
|
||||
```bash
|
||||
cd ~/Downloads
|
||||
curl -L -o Diligence.zip https://github.com/DiligenceWorks/Diligence/archive/refs/heads/main.zip
|
||||
unzip Diligence.zip
|
||||
cd Diligence-main
|
||||
```
|
||||
|
||||
Or with git (if installed):
|
||||
|
||||
```bash
|
||||
cd ~/Downloads
|
||||
git clone https://github.com/DiligenceWorks/Diligence.git Diligence-main
|
||||
cd Diligence-main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Install Diligence and dependencies
|
||||
|
||||
**Option A — System-wide (simpler):**
|
||||
|
||||
```bash
|
||||
cd ~/Downloads/Diligence-main
|
||||
pip3 install ".[mcp]" --break-system-packages
|
||||
```
|
||||
|
||||
The `--break-system-packages` flag is required on Ubuntu 23.04+ and Debian 12+
|
||||
due to PEP 668 (externally managed environments). It is safe for user-level
|
||||
installs.
|
||||
|
||||
**Option B — Virtual environment (cleaner):**
|
||||
|
||||
```bash
|
||||
cd ~/Downloads/Diligence-main
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install ".[mcp]"
|
||||
```
|
||||
|
||||
If using a venv, you must activate it (`source .venv/bin/activate`) each time
|
||||
before running Diligence.
|
||||
|
||||
**Note:** Unlike Windows, Linux does not need the `tzdata` pip package. The
|
||||
system timezone database at `/usr/share/zoneinfo/` is used automatically.
|
||||
|
||||
---
|
||||
|
||||
## 5. Start Diligence
|
||||
|
||||
```bash
|
||||
cd ~/Downloads/Diligence-main
|
||||
python3 -m diligence
|
||||
```
|
||||
|
||||
You should see:
|
||||
|
||||
```
|
||||
Diligence running at http://localhost:8000
|
||||
Data: /home/USERNAME/.diligence
|
||||
MCP: http://localhost:3001/sse
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
Open `http://localhost:8000` in your browser. Create an account on the
|
||||
registration page.
|
||||
|
||||
To run in the background:
|
||||
|
||||
```bash
|
||||
nohup python3 -m diligence > diligence.log 2>&1 &
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Prepare the MCP stdio launcher
|
||||
|
||||
Some AI agents (Claude Desktop) require stdio transport. Create the launcher:
|
||||
|
||||
```bash
|
||||
cat > ~/Downloads/Diligence-main/mcp_stdio.py << 'EOF'
|
||||
from diligence.mcp.server import create_mcp_server
|
||||
mcp = create_mcp_server(api_url="http://localhost:8000")
|
||||
mcp.run(transport="stdio")
|
||||
EOF
|
||||
```
|
||||
|
||||
Test it (Diligence must be running in another terminal):
|
||||
|
||||
```bash
|
||||
cd ~/Downloads/Diligence-main
|
||||
python3 mcp_stdio.py
|
||||
```
|
||||
|
||||
If it hangs with no output, that is success (stdio waiting for input). Ctrl+C to stop.
|
||||
|
||||
---
|
||||
|
||||
## 7. Connect an AI Agent
|
||||
|
||||
Choose one or more of the following options. All are free.
|
||||
|
||||
---
|
||||
|
||||
### 7a. Gemini CLI (recommended free option)
|
||||
|
||||
**What:** Google's terminal AI agent. 1,000 free requests/day with Google sign-in.
|
||||
Supports stdio and SSE MCP directly — no bridge needed.
|
||||
|
||||
**Requires:** Node.js (Step 2)
|
||||
|
||||
**Install:**
|
||||
|
||||
```bash
|
||||
npm install -g @google/gemini-cli
|
||||
```
|
||||
|
||||
**First run — authenticate with Google:**
|
||||
|
||||
```bash
|
||||
gemini
|
||||
```
|
||||
|
||||
Follow the browser prompt to sign in with your Google account. One-time setup.
|
||||
|
||||
**Configure MCP:**
|
||||
|
||||
Gemini CLI supports SSE directly, so you can point it straight at the running
|
||||
MCP server — no stdio script needed:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.gemini
|
||||
cat > ~/.gemini/settings.json << 'EOF'
|
||||
{
|
||||
"mcpServers": {
|
||||
"diligence": {
|
||||
"url": "http://localhost:3001/sse"
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
Alternatively, use the stdio launcher:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"diligence": {
|
||||
"command": "python3",
|
||||
"args": ["mcp_stdio.py"],
|
||||
"cwd": "/home/USERNAME/Downloads/Diligence-main"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace `USERNAME` with your actual username.
|
||||
|
||||
**Use:**
|
||||
|
||||
1. Start Diligence in one terminal (`python3 -m diligence`)
|
||||
2. Open a second terminal and run `gemini`
|
||||
3. Type: "What's my fitness status today?"
|
||||
|
||||
Gemini CLI will discover the Diligence MCP tools and use them to answer.
|
||||
|
||||
---
|
||||
|
||||
### 7b. Claude Desktop (free, Debian/Ubuntu only — beta)
|
||||
|
||||
**What:** Anthropic's desktop app. Free with a free Claude account.
|
||||
Official Linux beta released July 9, 2026. Debian/Ubuntu only.
|
||||
|
||||
**Requires:** Ubuntu 22.04+ or Debian 12+, free Claude account
|
||||
|
||||
**Install:**
|
||||
|
||||
```bash
|
||||
sudo curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc \
|
||||
https://downloads.claude.ai/claude-desktop/key.asc
|
||||
|
||||
echo "deb [signed-by=/usr/share/keyrings/claude-desktop-archive-keyring.asc] \
|
||||
https://downloads.claude.ai/claude-desktop/apt/stable stable main" \
|
||||
| sudo tee /etc/apt/sources.list.d/claude-desktop.list
|
||||
|
||||
sudo apt update && sudo apt install claude-desktop
|
||||
```
|
||||
|
||||
For Fedora, Arch, or other distros, see the community package at
|
||||
[github.com/aaddrick/claude-desktop-debian](https://github.com/aaddrick/claude-desktop-debian).
|
||||
|
||||
**Configure MCP:**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/Claude
|
||||
cat > ~/.config/Claude/claude_desktop_config.json << 'EOF'
|
||||
{
|
||||
"mcpServers": {
|
||||
"diligence": {
|
||||
"command": "python3",
|
||||
"args": ["mcp_stdio.py"],
|
||||
"cwd": "/home/USERNAME/Downloads/Diligence-main"
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
Replace `USERNAME` with your actual username.
|
||||
|
||||
If using a virtual environment, use the full path to the venv Python:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"diligence": {
|
||||
"command": "/home/USERNAME/Downloads/Diligence-main/.venv/bin/python",
|
||||
"args": ["mcp_stdio.py"],
|
||||
"cwd": "/home/USERNAME/Downloads/Diligence-main"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Use:**
|
||||
|
||||
1. Start Diligence in a terminal (`python3 -m diligence`)
|
||||
2. Quit and reopen Claude Desktop
|
||||
3. Look for a tools/hammer icon indicating MCP is connected
|
||||
4. Type: "What's my fitness status today?"
|
||||
|
||||
---
|
||||
|
||||
### 7c. ChatGPT Desktop (not available on Linux)
|
||||
|
||||
OpenAI has not released an official ChatGPT Desktop app for Linux as of
|
||||
August 2026. A sign-up page exists for future availability. Community wrappers
|
||||
(lencx/ChatGPT, Snap packages) do not support MCP.
|
||||
|
||||
If you have a ChatGPT paid plan, you can use the **Codex CLI** instead:
|
||||
|
||||
```bash
|
||||
npm install -g @openai/codex
|
||||
```
|
||||
|
||||
Codex CLI shares MCP configuration and supports stdio servers. Requires a
|
||||
ChatGPT Plus, Pro, or Team plan.
|
||||
|
||||
---
|
||||
|
||||
### 7d. Built-in AI Coach (simplest — no extra apps needed)
|
||||
|
||||
**What:** AI coaching chat built directly into the Diligence web app. No external
|
||||
tools, no config files, no MCP setup. Just needs a free API key.
|
||||
|
||||
**Free API key providers:**
|
||||
|
||||
| Provider | Free tier | Get key |
|
||||
|----------|-----------|---------|
|
||||
| OpenRouter | 26 free models | [openrouter.ai/keys](https://openrouter.ai/keys) |
|
||||
| Groq | Fast Llama inference | [console.groq.com/keys](https://console.groq.com/keys) |
|
||||
| Google AI Studio | Gemini Flash/Pro | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |
|
||||
| Hugging Face | Thousands of models | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) |
|
||||
| Ollama | Run LLMs locally, no key needed | [ollama.com](https://ollama.com/) |
|
||||
|
||||
**Setup:**
|
||||
|
||||
1. Sign up at one of the providers above and copy your API key
|
||||
2. In the Diligence browser app, go to **Settings > Integrations > AI Coaching**
|
||||
3. Paste your API key and select a model
|
||||
4. Use the **Coach** tab in the bottom navigation
|
||||
|
||||
**Ollama (fully offline):**
|
||||
|
||||
If you want AI coaching without any internet dependency:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://ollama.com/install.sh | sh
|
||||
ollama pull llama3.1
|
||||
```
|
||||
|
||||
Then configure Diligence AI Coaching to point at `http://localhost:11434`.
|
||||
No API key needed.
|
||||
|
||||
---
|
||||
|
||||
## Daily Usage
|
||||
|
||||
Each time you want to use Diligence:
|
||||
|
||||
```bash
|
||||
cd ~/Downloads/Diligence-main
|
||||
python3 -m diligence
|
||||
```
|
||||
|
||||
If using a venv:
|
||||
|
||||
```bash
|
||||
cd ~/Downloads/Diligence-main
|
||||
source .venv/bin/activate
|
||||
python3 -m diligence
|
||||
```
|
||||
|
||||
Open `http://localhost:8000` in your browser. The app runs until you press Ctrl+C.
|
||||
|
||||
If using an external AI agent (Gemini CLI, Claude Desktop), make sure Diligence
|
||||
is running first, then open the agent.
|
||||
|
||||
---
|
||||
|
||||
## Optional: Run as a systemd service
|
||||
|
||||
To start Diligence automatically on boot:
|
||||
|
||||
```bash
|
||||
sudo tee /etc/systemd/system/diligence.service << EOF
|
||||
[Unit]
|
||||
Description=Diligence Fitness
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=$USER
|
||||
WorkingDirectory=$HOME/Downloads/Diligence-main
|
||||
ExecStart=$(which python3) -m diligence
|
||||
Restart=on-failure
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now diligence
|
||||
```
|
||||
|
||||
Check status:
|
||||
|
||||
```bash
|
||||
sudo systemctl status diligence
|
||||
journalctl -u diligence -f
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Updating
|
||||
|
||||
```bash
|
||||
cd ~/Downloads
|
||||
rm -rf Diligence-main
|
||||
curl -L -o Diligence.zip https://github.com/DiligenceWorks/Diligence/archive/refs/heads/main.zip
|
||||
unzip Diligence.zip
|
||||
cd Diligence-main
|
||||
pip3 install ".[mcp]" --break-system-packages
|
||||
```
|
||||
|
||||
Or with git:
|
||||
|
||||
```bash
|
||||
cd ~/Downloads/Diligence-main
|
||||
git pull origin main
|
||||
pip3 install ".[mcp]" --break-system-packages
|
||||
```
|
||||
|
||||
Your data is stored in `~/.diligence/` and is preserved across updates.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Cause | Fix |
|
||||
|---------|-------|-----|
|
||||
| "No module named diligence" | Wrong directory or venv not active | `cd ~/Downloads/Diligence-main` and `source .venv/bin/activate` if using venv |
|
||||
| "No module named uvicorn" | Dependencies not installed | `pip3 install ".[mcp]" --break-system-packages` |
|
||||
| "No module named mcp.server.fastmcp" | Wrong MCP SDK version | `pip3 uninstall mcp -y && pip3 install "fastmcp>=3.0.0" --break-system-packages` |
|
||||
| "externally-managed-environment" | PEP 668 on Ubuntu 23.04+ | Add `--break-system-packages` or use a venv |
|
||||
| MCP line shows "not available" | Missing MCP extras | `pip3 install ".[mcp]" --break-system-packages` |
|
||||
| Claude Desktop MCP not loading | Wrong config path | Check `~/.config/Claude/claude_desktop_config.json` exists |
|
||||
| Gemini CLI "no tools found" | Settings path wrong | Check `~/.gemini/settings.json` has correct `cwd` path |
|
||||
| Port 8000 already in use | Another service on that port | `python3 -m diligence --port 8080` or stop the conflicting service |
|
||||
Loading…
Add table
Add a link
Reference in a new issue