d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
3e9645274a5f6e2cbc5bae1dff55d3aed0295cbf
proxmox/README.md
defiQUG ed85135249 docs: use Gitea for internal repo references (FusionAI, cross-chain-pmm-lps, clone URL) 
- Sankofa/FusionAI-Creator: REPO_URL and doc links → gitea.d-bis.org/d-bis/FusionAI-Creator
- cross-chain-pmm-lps doc link → Gitea
- trust-wallet registry source → gitea.d-bis.org/d-bis
- README: clone URL and note that canonical source is Gitea; public refs (GRU policy, token lists) stay on GitHub

Made-with: Cursor
2026-03-02 11:34:56 -08:00

323 lines
11 KiB
Markdown
Raw Blame History

# Proxmox Project Workspace
This workspace contains multiple Proxmox-related projects managed as a monorepo using pnpm workspaces.
## Project Structure
- **`mcp-proxmox/`** - Proxmox MCP (Model Context Protocol) Server - Node.js-based server for interacting with Proxmox hypervisors
- **`ProxmoxVE/`** - ProxmoxVE Helper Scripts - Collection of scripts and frontend for managing Proxmox containers and VMs
- **`smom-dbis-138/`** - Blockchain network and services (Chain 138); **`smom-dbis-138-proxmox/`** - Deployment scripts (if present)
- For the full submodule list and relationships, see [docs/11-references/SUBMODULE_RELATIONSHIP_MAP.md](docs/11-references/SUBMODULE_RELATIONSHIP_MAP.md)
- **Documentation:** [docs/README.md](docs/README.md) · [docs/MASTER_INDEX.md](docs/MASTER_INDEX.md) · Next steps: [docs/00-meta/NEXT_STEPS_INDEX.md](docs/00-meta/NEXT_STEPS_INDEX.md). Root status reports moved to [docs/archive/](docs/archive/README.md) (2026-02-20).
## Prerequisites
- Node.js 16+
- pnpm 8+
- Git (for submodule management)
## Setup
### Quick Setup
Run the automated setup script:
```bash
./scripts/setup.sh
```
This will:
- Create `.env` file from template (if it doesn't exist)
- Create Claude Desktop configuration (if it doesn't exist)
- Install all workspace dependencies
### Manual Setup
1. **Clone the repository** (if not already done). Canonical source is **Gitea** (use Gitea for clone and internal repo references; public references such as GRU Monetary Policy and token lists remain on GitHub where applicable):
```bash
git clone https://gitea.d-bis.org/d-bis/proxmox.git
cd proxmox
```
2. **Initialize and update submodules**:
```bash
git submodule update --init --recursive
```
3. **Install dependencies**:
```bash
pnpm install
```
4. **Configure environment**:
```bash
# Recommended: run setup to create .env in repo root and ~/.env from .env.example
./scripts/setup.sh
# Or manually: copy template to repo root and/or home
cp .env.example .env
# and/or: cp .env.example ~/.env
# Edit with your Proxmox, Cloudflare, NPM credentials (see .env.example)
nano .env
```
5. **Configure Claude Desktop**:
```bash
# Copy config template
mkdir -p ~/.config/Claude
cp claude_desktop_config.json.example ~/.config/Claude/claude_desktop_config.json
# Verify the path in the config file is correct
```
6. **Verify setup**:
```bash
./scripts/verify-setup.sh
```
This will install dependencies for all workspace packages and set up configuration files.
## Available Scripts
From the root directory, you can run:
### MCP Server Commands
- `pnpm mcp:start` - Start the Proxmox MCP server
- `pnpm mcp:dev` - Start the MCP server in development mode (with watch)
### Frontend Commands
- `pnpm frontend:dev` - Start the ProxmoxVE frontend development server
- `pnpm frontend:build` - Build the ProxmoxVE frontend for production
- `pnpm frontend:start` - Start the production frontend server
### Testing
- `pnpm test` - Run tests (if available)
- `pnpm test:basic` - Run basic MCP server tests (read-only operations)
- `pnpm test:workflows` - Run comprehensive workflow tests (requires elevated permissions)
### UniFi Commands
- `pnpm unifi:build` - Build UniFi API and MCP server packages
- `pnpm unifi:start` - Start the UniFi MCP server
- `pnpm unifi:dev` - Start the UniFi MCP server in development mode
- `pnpm unifi:cli` - Run UniFi CLI tool
## RPC Node Health, Testing, and Remediation (Chain 138)
This repo includes scripts to **test all RPC nodes**, **audit Proxmox storage restrictions**, and **enforce safe Besu heap sizing** to prevent swap/IO thrash.
### Run the full health suite (recommended)
```bash
PROXMOX_HOST=192.168.11.10 ./scripts/run-rpc-node-suite.sh
```
- Writes RPC test reports under `reports/` (JSON + Markdown).
- Runs remediation in **dry-run** mode by default.
### Apply remediation (only if you intend to change Proxmox / containers)
```bash
PROXMOX_HOST=192.168.11.10 ./scripts/run-rpc-node-suite.sh --apply --restart-besu
```
### Individual tools
```bash
# Full RPC matrix test (no Proxmox access required)
python3 ./scripts/test-all-rpc-nodes.py
# Proxmox audits
PROXMOX_HOST=192.168.11.10 ./scripts/audit-proxmox-rpc-storage.sh
PROXMOX_HOST=192.168.11.10 ./scripts/audit-proxmox-rpc-besu-heap.sh
# Idempotent remediation (dry-run by default)
PROXMOX_HOST=192.168.11.10 ./scripts/remediate-proxmox-rpc-stability.sh
```
## Workspace Packages
### mcp-proxmox-server
The Proxmox MCP server provides a Model Context Protocol interface for managing Proxmox hypervisors.
**Features:**
- 55+ MCP tools for Proxmox management
- Configurable permission levels (basic vs elevated)
- Secure token-based authentication
- Support for VMs, containers, storage, snapshots, backups, and more
See [mcp-proxmox/README.md](docs/01-getting-started/README.md) for detailed documentation.
**Configuration:**
See [docs/MCP_SETUP.md](docs/04-configuration/MCP_SETUP.md) for instructions on configuring the MCP server with Claude Desktop.
### proxmox-helper-scripts-website
A Next.js frontend for browsing and managing Proxmox helper scripts.
**Features:**
- Browse available container and VM scripts
- View script details, requirements, and installation instructions
- JSON editor for script metadata
- Category and version management
See [ProxmoxVE/frontend/README.md](docs/01-getting-started/README.md) for more information.
### unifi-api & mcp-unifi-server
UniFi API client library and MCP server for managing Ubiquiti UniFi/UDM Pro devices.
**Features:**
- Type-safe API client with full TypeScript support
- Dual API mode support (Official Local API and Private Controller API)
- MCP server for Claude Desktop integration
- CLI tool for common operations
- Utility scripts for monitoring and health checks
See [unifi-api/README.md](unifi-api/README.md) for API client documentation.
See [mcp-unifi/README.md](mcp-unifi/README.md) for MCP server documentation.
**Configuration:**
See [docs/04-configuration/UNIFI_API_SETUP.md](docs/04-configuration/UNIFI_API_SETUP.md) for setup instructions.
## Environment Configuration
### MCP Server Configuration
The MCP server loads configuration from `/home/intlc/.env` (one directory up from the project root). Create this file with:
```bash
PROXMOX_HOST=your-proxmox-ip-or-hostname
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-secret
PROXMOX_ALLOW_ELEVATED=false
PROXMOX_PORT=8006
```
See [docs/MCP_SETUP.md](docs/04-configuration/MCP_SETUP.md) for detailed configuration instructions.
## Development
### Working with Submodules
To update submodules to their latest versions:
```bash
git submodule update --remote
```
To update a specific submodule:
```bash
cd mcp-proxmox
git pull origin main
cd ..
git add mcp-proxmox
git commit -m "Update mcp-proxmox submodule"
```
### Adding New Dependencies
To add a dependency to a specific workspace package:
```bash
pnpm --filter mcp-proxmox-server add <package-name>
pnpm --filter proxmox-helper-scripts-website add <package-name>
```
To add a dev dependency:
```bash
pnpm --filter <package-name> add -D <package-name>
```
## Project Structure
```
proxmox/
├── scripts/ # Project root utility scripts
├── docs/ # Project documentation
├── mcp-proxmox/ # MCP Server submodule
├── ProxmoxVE/ # ProxmoxVE Helper Scripts submodule
├── fireblocks-integration/ # Fireblocks Web3 (Chain 138) submodule (Gitea)
└── smom-dbis-138-proxmox/ # Deployment scripts submodule
```
See [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) for detailed structure documentation.
## How to Navigate This Repo
**New to this repository?** Start here:
- **[ROOT_INDEX.md](ROOT_INDEX.md)** - Quick navigation index for newcomers and auditors
- **[DIRECTORY_REFERENCE.md](DIRECTORY_REFERENCE.md)** - Complete directory structure and organization guide
- **[docs/MASTER_INDEX.md](docs/MASTER_INDEX.md)** - Documentation index (deployment, architecture, services)
- **[PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)** - Project and docs structure
**Organization principles:** This repository uses a **flat + indexed** structure. The three-layer separation (control plane / core systems / ops evidence) is a **mental model**, not an enforced structure. See [docs/MASTER_INDEX.md](docs/MASTER_INDEX.md) and [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) for structure and intent.
## Project Documentation
### Setup & Configuration
- [docs/MCP_SETUP.md](docs/04-configuration/MCP_SETUP.md) - MCP Server configuration guide
- [docs/PREREQUISITES.md](docs/01-getting-started/PREREQUISITES.md) - Prerequisites and requirements
- [docs/ENV_STANDARDIZATION.md](docs/04-configuration/ENV_STANDARDIZATION.md) - Environment variable standardization
### Quick References
- [docs/12-quick-reference/QUICK_REFERENCE.md](docs/12-quick-reference/QUICK_REFERENCE.md) - Quick reference for ProxmoxVE scripts
- [docs/12-quick-reference/QUICK_REFERENCE_CARDS.md](docs/12-quick-reference/QUICK_REFERENCE_CARDS.md) - Network, VMID, commands, troubleshooting cards
- [docs/01-getting-started/README_START_HERE.md](docs/01-getting-started/README_START_HERE.md) - Getting started guide
### Deployment
- [docs/03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md](docs/03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md) - Deployment status
- [docs/03-deployment/DEPLOYMENT_READINESS.md](docs/03-deployment/DEPLOYMENT_READINESS.md) - Deployment readiness checklist
- **Next steps (master list):** [docs/00-meta/NEXT_STEPS_MASTER.md](docs/00-meta/NEXT_STEPS_MASTER.md)
- **CCIP WETH9 Bridge (Chain 138):** `./scripts/deploy-and-configure-weth9-bridge-chain138.sh` (use `--dry-run` to simulate) then set `CCIPWETH9_BRIDGE_CHAIN138`; see [COMPREHENSIVE_STATUS_BRIDGE_READY.md](COMPREHENSIVE_STATUS_BRIDGE_READY.md), [docs/07-ccip/README.md](docs/07-ccip/README.md), [scripts/README.md](scripts/README.md)
### Project Documentation
- [mcp-proxmox/README.md](mcp-proxmox/README.md) - MCP Server detailed documentation
- [ProxmoxVE/README.md](ProxmoxVE/README.md) - ProxmoxVE scripts documentation
### Multi-Chain Integration
- [ALL Mainnet Integration](ALL_MAINNET_MASTER_DOCUMENTATION.md) - Complete ALL Mainnet (651940) integration guide
- [ALL Mainnet Master Documentation](ALL_MAINNET_MASTER_DOCUMENTATION.md) - Quick reference for ALL Mainnet configuration
## Deployment Status
### ✅ Ready for Deployment
**Current Status:** All validations passing (100%)
- ✅ Prerequisites: 33/33 (100%)
- ✅ Deployment Validation: 41/41 (100%)
- ✅ API Connection: Working (Proxmox 9.1.1)
- ✅ Target Node: ml110 (online)
**Quick Deploy:**
```bash
cd smom-dbis-138-proxmox
sudo ./scripts/deployment/deploy-all.sh
```
See [docs/03-deployment/DEPLOYMENT_READINESS.md](docs/03-deployment/DEPLOYMENT_READINESS.md) for complete deployment guide.
## Validation
Run comprehensive validation:
```bash
./scripts/complete-validation.sh
```
Individual checks:
- `./scripts/check-prerequisites.sh` - Prerequisites validation
- `./scripts/validate-ml110-deployment.sh` - Deployment validation
- `./scripts/test-connection.sh` - Connection testing
## License
This workspace contains multiple projects with different licenses. Please refer to individual project directories for license information.
Reference in New Issue View Git Blame Copy Permalink