Table of Contents

• Overview
• Architecture
  • Core Concepts
  • Design
  • Trade-offs
• Usage
  • Requirements
  • Lifecycle
  • Getting Started
    • Development and Container Extension

---

Overview

Proxmox-GitOps implements a self-sufficient, extensible CI/CD environment for provisioning, configuring, and orchestrating Linux Containers (LXC) within Proxmox VE. Leveraging an Infrastructure-as-Code (IaC) approach, it manages the entire container lifecycle—bootstrapping, deployment, configuration, and validation—through version-controlled automation.

Architecture

The architecture is based on a multi-stage pipeline capable of recursively deploying and configuring itself as a self-managed control plane.

Initial bootstrapping is performed via a local Docker environment, with subsequent deployments targeting Proxmox VE.

Core Concepts

This system implements stateless infrastructure management on Proxmox VE, ensuring deterministic reproducibility and environmental parity through recursive self-containment.

Concept	Approach	Reasoning
Ephemeral State	Git repository represents current desired state, ensuring state purity across deployments.	Deployment consistency and stateless infrastructure over version history.
Recursive Self-Containment	Embedded control plane recursively provisions itself within target containers, ensuring deterministic bootstrap.	Prevents configuration drift; enables consistent and reproducible behavior.
Dynamic Orchestration	Imperative logic (e.g. config/recipes/repo.rb) used for dynamic, cross-layer state management	Declarative approach intractable for adjusting to dynamic cross-layer changes (e.g. submodule remote rewriting).
Monorepository	Centralizes infrastructure as a single code artifact; submodules modularize development at runtime	Consistency and modularity: infrastructure self-contained; dynamically resolved in recursive context.

Design

• Loosely coupled: Containers are decoupled from the control plane, enabling runtime replacement and independent operation.

• Headless container configuration: By convention, Ansible is used for provisioning (community.proxmox upstream); Cinc (Chef) handles modular, recursive desired state complexity.

Trade-offs

• Complexity vs. Autonomy: Recursive self-replication increases complexity drastically to achieve integrated deterministic bootstrap and reproducing behavior.

• Git Convention vs. Infrastructure State: Uses Git as a state engine rather than versioning in volatile, stateless contexts. Monorepository representation, however, encapsulates the entire infrastructure as a self-contained asset suited for version control.

• API Token Restriction vs. Automation: With Proxmox 9, stricter privilege separation prevents privileged containers from mounting shares via API token; automation capabilities, however, are mainly within the root user context. As a consequence, root user-based API access takes precedence over token-based authentication.

Usage

Requirements

• Docker
• Proxmox VE 8.4-9.0
• Proxmox API token
• See Wiki for recommendations

Lifecycle

• Self-contained Monorepository Artifact for Version-Controlled Mirroring

  • git clone --recurse-submodules (store /share for persistence, disable network access for security)

• Backup: See previous

• Update: See previous, and redeploy merged

• Rollback: See previous, or set snapshot to release at runtime

Getting Started

• Set credentials and Proxmox API token in local/.config.json as ./local/config.json
• Run ./local/run.sh for local Docker environment
• Accept the Pull Request at localhost:8080/main/config/pulls/1 to deploy on Proxmox VE

Development and Container Extension

Reusable container definitions are stored in the libs folder.

Copy an example container (like libs/broker or libs/proxy) as a template, or create a new container lib from scratch and follow these steps:

• Add config.env to your container's root directory (e.g. ./libs/apache):

IP=192.168.178.42
ID=42
HOSTNAME=apache
CORES=2
MEMORY=2048
SWAP=512
DISK=local-lvm:8
BOOT=yes

• Add your cookbook to the container definition root:

# libs/apache/recipes/default.rb
package 'apache2'

file '/var/www/html/index.html' do
  content "<h1>Hello from #{Env.get(node, 'login')}</h1>"
  mode '0644'
  owner 'app'    # see base/roles/base/tasks/main.yml
  group 'config' # each container is configured identically 
end

Common.application(self, 'apache2') # provided by convention

• Optionally, use Env.get() and Env.set() to access Gitea environment variables.

• Add to Monorepository and redeploy.

The container can be tested locally running ./local/run.sh [container] (wip)