proxmox/docs/01-getting-started/PREREQUISITES.md

# Prerequisites and Setup Requirements

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

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 (automation / jump host)

Useful when running `scripts/push-templates-to-proxmox.sh`, verification, or SSH-based automation:

- **sshpass** — Non-interactive SSH with password when keys are not set (optional; prefer SSH keys).
- **rsync** — Efficient file sync for template push (script falls back to scp if missing).
- **dnsutils**, **iproute2** — `dig`, `ss` for DNS/socket checks.
- **screen** or **tmux** — Long-running deployment sessions.
- **htop** — Process monitoring.
- **shellcheck** — For `scripts/verify/run-shellcheck.sh`.
- **parallel** — GNU parallel for batch operations.

**Install (Debian/Ubuntu):** `sudo apt install -y sshpass rsync dnsutils iproute2 screen tmux htop shellcheck parallel`  
**Full list:** [11-references/APT_PACKAGES_CHECKLIST.md](../11-references/APT_PACKAGES_CHECKLIST.md) § Automation / jump host.

### Optional but recommended (deployment)

- **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`