Refactor code for improved readability and performance
This commit is contained in:
defiQUG
233
docs/01-getting-started/PREREQUISITES.md
Normal file
233
docs/01-getting-started/PREREQUISITES.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# Prerequisites and Setup Requirements
|
||||
|
||||
Complete list of prerequisites and setup steps for the Proxmox workspace.
|
||||
|
||||
## System Prerequisites
|
||||
|
||||
### Required Software
|
||||
|
||||
1. **Node.js**
|
||||
- Version: 16.0.0 or higher
|
||||
- Check: `node --version`
|
||||
- Install: Download from [nodejs.org](https://nodejs.org/) or use package manager
|
||||
|
||||
2. **pnpm**
|
||||
- Version: 8.0.0 or higher
|
||||
- Check: `pnpm --version`
|
||||
- Install: `npm install -g pnpm`
|
||||
|
||||
3. **Git**
|
||||
- Any recent version
|
||||
- Check: `git --version`
|
||||
- Install: Usually pre-installed on Linux/Mac
|
||||
|
||||
### Optional but Recommended
|
||||
|
||||
- **Proxmox VE** (if deploying containers)
|
||||
- Version: 7.0+ or 8.4+/9.0+
|
||||
- For local development, you can use the MCP server to connect to remote Proxmox
|
||||
|
||||
## Workspace Prerequisites
|
||||
|
||||
### 1. Repository Setup
|
||||
|
||||
```bash
|
||||
# Clone repository (if applicable)
|
||||
git clone <repository-url>
|
||||
cd proxmox
|
||||
|
||||
# Initialize submodules
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
### 2. Workspace Structure
|
||||
|
||||
Required structure:
|
||||
```
|
||||
proxmox/
|
||||
├── package.json # Root workspace config
|
||||
├── pnpm-workspace.yaml # Workspace definition
|
||||
├── mcp-proxmox/ # MCP server submodule
|
||||
│ ├── index.js
|
||||
│ └── package.json
|
||||
└── ProxmoxVE/ # Helper scripts submodule
|
||||
└── frontend/
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### 3. Dependencies Installation
|
||||
|
||||
```bash
|
||||
# Install all workspace dependencies
|
||||
pnpm install
|
||||
```
|
||||
|
||||
This installs dependencies for:
|
||||
- `mcp-proxmox-server` - MCP server packages
|
||||
- `proxmox-helper-scripts-website` - Frontend packages
|
||||
|
||||
## Configuration Prerequisites
|
||||
|
||||
### 1. Environment Variables (.env)
|
||||
|
||||
Location: `/home/intlc/.env`
|
||||
|
||||
Required variables:
|
||||
```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
|
||||
```
|
||||
|
||||
Optional variables:
|
||||
```bash
|
||||
PROXMOX_PORT=8006 # Defaults to 8006
|
||||
```
|
||||
|
||||
### 2. Claude Desktop Configuration
|
||||
|
||||
Location: `~/.config/Claude/claude_desktop_config.json`
|
||||
|
||||
Required configuration:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"proxmox": {
|
||||
"command": "node",
|
||||
"args": ["/home/intlc/projects/proxmox/mcp-proxmox/index.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Proxmox Server Prerequisites (if deploying)
|
||||
|
||||
### 1. Proxmox VE Installation
|
||||
|
||||
- Version 7.0+ or 8.4+/9.0+
|
||||
- Access to Proxmox web interface
|
||||
- API access enabled
|
||||
|
||||
### 2. API Token Creation
|
||||
|
||||
Create API token via Proxmox UI:
|
||||
1. Log into Proxmox web interface
|
||||
2. Navigate to **Datacenter** → **Permissions** → **API Tokens**
|
||||
3. Click **Add** to create new token
|
||||
4. Save Token ID and Secret
|
||||
|
||||
Or use the script:
|
||||
```bash
|
||||
./scripts/create-proxmox-token.sh <host> <user> <password> <token-name>
|
||||
```
|
||||
|
||||
### 3. LXC Template (for container deployments)
|
||||
|
||||
Download base template:
|
||||
```bash
|
||||
pveam download local debian-12-standard_12.2-1_amd64.tar.zst
|
||||
```
|
||||
|
||||
Or use `all-templates.sh` script:
|
||||
```bash
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/tools/addon/all-templates.sh)"
|
||||
```
|
||||
|
||||
## Verification Steps
|
||||
|
||||
### 1. Run Complete Setup
|
||||
|
||||
```bash
|
||||
./scripts/complete-setup.sh
|
||||
```
|
||||
|
||||
This script verifies and completes:
|
||||
- ✅ Prerequisites check
|
||||
- ✅ Submodule initialization
|
||||
- ✅ Dependency installation
|
||||
- ✅ Configuration file creation
|
||||
- ✅ Final verification
|
||||
|
||||
### 2. Run Verification Script
|
||||
|
||||
```bash
|
||||
./scripts/verify-setup.sh
|
||||
```
|
||||
|
||||
### 3. Test MCP Server
|
||||
|
||||
```bash
|
||||
# Test basic functionality (requires .env configured)
|
||||
pnpm test:basic
|
||||
|
||||
# Start MCP server
|
||||
pnpm mcp:start
|
||||
```
|
||||
|
||||
## Quick Setup Checklist
|
||||
|
||||
- [ ] Node.js 16+ installed
|
||||
- [ ] pnpm 8+ installed
|
||||
- [ ] Git installed
|
||||
- [ ] Repository cloned
|
||||
- [ ] Submodules initialized
|
||||
- [ ] Dependencies installed (`pnpm install`)
|
||||
- [ ] `.env` file created and configured
|
||||
- [ ] Claude Desktop config created
|
||||
- [ ] (Optional) Proxmox API token created
|
||||
- [ ] (Optional) LXC template downloaded
|
||||
- [ ] Verification script passes
|
||||
|
||||
## Troubleshooting Prerequisites
|
||||
|
||||
### Node.js Issues
|
||||
|
||||
```bash
|
||||
# Check version
|
||||
node --version
|
||||
|
||||
# Install/update via nvm (recommended)
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
nvm install 18
|
||||
nvm use 18
|
||||
```
|
||||
|
||||
### pnpm Issues
|
||||
|
||||
```bash
|
||||
# Install globally
|
||||
npm install -g pnpm
|
||||
|
||||
# Or use corepack (Node.js 16.9+)
|
||||
corepack enable
|
||||
corepack prepare pnpm@latest --activate
|
||||
```
|
||||
|
||||
### Submodule Issues
|
||||
|
||||
```bash
|
||||
# Force update submodules
|
||||
git submodule update --init --recursive --force
|
||||
|
||||
# If submodules are outdated
|
||||
git submodule update --remote
|
||||
```
|
||||
|
||||
### Dependency Issues
|
||||
|
||||
```bash
|
||||
# Clean install
|
||||
rm -rf node_modules */node_modules */*/node_modules
|
||||
rm -rf pnpm-lock.yaml */pnpm-lock.yaml
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## Next Steps After Prerequisites
|
||||
|
||||
1. **Configure Proxmox credentials** in `.env`
|
||||
2. **Restart Claude Desktop** (if using MCP server)
|
||||
3. **Test connection** with `pnpm test:basic`
|
||||
4. **Start development** with `pnpm mcp:dev` or `pnpm frontend:dev`
|
||||
|
||||
21
docs/01-getting-started/README.md
Normal file
21
docs/01-getting-started/README.md
Normal file
@@ -0,0 +1,21 @@
|
||||
# Getting Started
|
||||
|
||||
This directory contains documentation for first-time setup and getting started with the project.
|
||||
|
||||
## Documents
|
||||
|
||||
- **[README_START_HERE.md](README_START_HERE.md)** - Complete getting started guide - **START HERE**
|
||||
- **[PREREQUISITES.md](PREREQUISITES.md)** - System requirements and prerequisites
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Read **[README_START_HERE.md](README_START_HERE.md)** for complete getting started instructions
|
||||
2. Review **[PREREQUISITES.md](PREREQUISITES.md)** to ensure all requirements are met
|
||||
3. Proceed to **[../02-architecture/](../02-architecture/)** for architecture overview
|
||||
4. Follow **[../03-deployment/](../03-deployment/)** for deployment guides
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **[../MASTER_INDEX.md](../MASTER_INDEX.md)** - Complete documentation index
|
||||
- **[../README.md](../README.md)** - Documentation overview
|
||||
|
||||
114
docs/01-getting-started/README_START_HERE.md
Normal file
114
docs/01-getting-started/README_START_HERE.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# 🚀 Quick Start Guide
|
||||
|
||||
Your Proxmox workspace is **fully configured and ready to use**!
|
||||
|
||||
## ✅ What's Configured
|
||||
|
||||
- ✅ All prerequisites installed (Node.js, pnpm, Git)
|
||||
- ✅ Workspace setup complete
|
||||
- ✅ All dependencies installed
|
||||
- ✅ Proxmox connection configured
|
||||
- Host: 192.168.11.10 (ml110.sankofa.nexus)
|
||||
- User: root@pam
|
||||
- API Token: mcp-server ✅
|
||||
- ✅ Claude Desktop configuration ready
|
||||
- ✅ MCP Server: 57 tools available
|
||||
|
||||
## 🎯 Get Started in 30 Seconds
|
||||
|
||||
### Start the MCP Server
|
||||
|
||||
```bash
|
||||
# Production mode
|
||||
pnpm mcp:start
|
||||
|
||||
# Development mode (auto-reload on changes)
|
||||
pnpm mcp:dev
|
||||
```
|
||||
|
||||
### Test the Connection
|
||||
|
||||
```bash
|
||||
# Test basic operations
|
||||
pnpm test:basic
|
||||
|
||||
# Or run connection test
|
||||
./scripts/test-connection.sh
|
||||
```
|
||||
|
||||
## 📚 What You Can Do
|
||||
|
||||
With the MCP server running, you can:
|
||||
|
||||
### Basic Operations (Available Now)
|
||||
- ✅ List Proxmox nodes
|
||||
- ✅ List VMs and containers
|
||||
- ✅ View storage information
|
||||
- ✅ Check cluster status
|
||||
- ✅ List available templates
|
||||
- ✅ Get VM/container details
|
||||
|
||||
### Advanced Operations (Requires `PROXMOX_ALLOW_ELEVATED=true`)
|
||||
- Create/delete VMs and containers
|
||||
- Start/stop/reboot VMs
|
||||
- Manage snapshots and backups
|
||||
- Configure disks and networks
|
||||
- And much more!
|
||||
|
||||
## ⚙️ Enable Advanced Features (Optional)
|
||||
|
||||
If you need to create or modify VMs:
|
||||
|
||||
1. Edit `~/.env`:
|
||||
```bash
|
||||
nano ~/.env
|
||||
```
|
||||
|
||||
2. Change:
|
||||
```
|
||||
PROXMOX_ALLOW_ELEVATED=false
|
||||
```
|
||||
|
||||
To:
|
||||
```
|
||||
PROXMOX_ALLOW_ELEVATED=true
|
||||
```
|
||||
|
||||
⚠️ **Warning**: This enables destructive operations. Only enable if needed.
|
||||
|
||||
## 📖 Documentation
|
||||
|
||||
- **Main README**: [README.md](README.md)
|
||||
- **MCP Setup Guide**: [docs/MCP_SETUP.md](docs/MCP_SETUP.md)
|
||||
- **Prerequisites**: [docs/PREREQUISITES.md](docs/PREREQUISITES.md)
|
||||
- **Setup Status**: [SETUP_STATUS.md](SETUP_STATUS.md)
|
||||
- **Complete Setup**: [SETUP_COMPLETE_FINAL.md](SETUP_COMPLETE_FINAL.md)
|
||||
|
||||
## 🛠️ Useful Commands
|
||||
|
||||
```bash
|
||||
# Verification
|
||||
./scripts/verify-setup.sh # Verify current setup
|
||||
./scripts/test-connection.sh # Test Proxmox connection
|
||||
|
||||
# MCP Server
|
||||
pnpm mcp:start # Start server
|
||||
pnpm mcp:dev # Development mode
|
||||
pnpm test:basic # Test operations
|
||||
|
||||
# Frontend
|
||||
pnpm frontend:dev # Start frontend dev server
|
||||
pnpm frontend:build # Build for production
|
||||
```
|
||||
|
||||
## 🎉 You're All Set!
|
||||
|
||||
Everything is configured and ready. Just start the MCP server and begin managing your Proxmox infrastructure!
|
||||
|
||||
---
|
||||
|
||||
**Quick Reference**:
|
||||
- Configuration: `~/.env`
|
||||
- MCP Server: `mcp-proxmox/index.js`
|
||||
- Documentation: See files above
|
||||
|
||||
Reference in New Issue
Block a user