CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Pulumi TypeScript project (proxmox-infra) for provisioning VMs and LXC containers in Proxmox using the @muhlba91/pulumi-proxmoxve provider. The stack name is dev.

Common Commands

# Install dependencies
npm install

# Preview infrastructure changes
pulumi preview

# Sync Pulumi state with actual Proxmox state (run before up if resources were changed manually)
pulumi refresh --yes

# Deploy infrastructure
pulumi refresh --yes && pulumi up --yes

# Destroy infrastructure
pulumi destroy

# View current stack outputs
pulumi stack output

# View stack config
pulumi config

Architecture

Entry point: index.ts — all Pulumi resources are declared here
Provider: @muhlba91/pulumi-proxmoxve v8.x — community Proxmox provider (not an official Pulumi provider)
Stack: dev — configured in Pulumi.dev.yaml
Runtime: Node.js with npm, TypeScript compiled to bin/ (excluded from git)

CI/CD (Gitea Actions)

Workflow file: ../.gitea/workflows/deploy-proxmox-infra.yaml

Triggers: push to main and pull requests targeting main, scoped to changes under proxmox-infra/** or .gitea/workflows/**.

Pull request → pulumi preview (no changes deployed)
Push to main → pulumi refresh then pulumi up

Secrets required in Gitea (Settings → Actions → Secrets):

PULUMI_BACKEND_URL — PostgreSQL connection string for the self-hosted state backend
PULUMI_CONFIG_PASSPHRASE — passphrase used to decrypt secrets in Pulumi.dev.yaml
PULUMI_DEV_YAML — base64-encoded content of Pulumi.dev.yaml (auto-synced by pre-push hook)

Key Notes

Credentials for both Proxmox nodes are stored as encrypted secrets in Pulumi.dev.yaml and decrypted at runtime using PULUMI_CONFIG_PASSPHRASE. Do not pass Proxmox credentials via environment variables — the code uses config.requireSecret().
There are two Proxmox providers: pveProvider (main node pve) and pveBckpProvider (backup node pve-bckp). Always pass the correct provider when adding resources.
Pulumi.dev.yaml contains the encryption salt — never delete it or secrets become unrecoverable.
TypeScript is compiled with strict mode, nodenext module resolution, and noImplicitReturns — all functions must have explicit return types when TypeScript cannot infer them.
Don't add a co-author when committing to git.

2.5 KiB Raw Blame History