• Overview
• Architecture
  • Core Concepts
  • Design
  • Trade-offs
• Usage
  • Requirements
  • Deployment
  • Files and Configuration
  • Lifecycle
    • Default Pipeline
    • Self-Containment
  • Development and Extension
    • Getting Started
    • Environment

Proxmox-GitOps implements a self-contained GitOps environment for provisioning and orchestrating Linux Containers (LXC) on Proxmox VE.

Encapsulating infrastructure within an extensible monorepository - recursively resolved from Git submodules at runtime - it provides a comprehensive Infrastructure-as-Code (IaC) abstraction for an entire, automated container-based infrastructure.

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.

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

• 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.

• Integrated Baseline: The base role standardizes defaults in container configuration. The control plane leverages this baseline and uses built-in infrastructure libraries to deploy itself recursively, establishing an operational pattern that is reproduced in container libs.

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

• Git Convention vs. Infrastructure State: Uses Git as a state engine rather than for 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.

• Docker
• Proxmox VE 8.4-9.1
  • Ensure storage settings.
• See Wiki for recommendations

• Set Proxmox VE host and default account credentials in local/config.json.

• Adjust environment configuration in globals.json.

• Ensure container configuration in container.env.

• Run ./local/run.sh for local Docker environment.

• Accept the Pull Request at http://localhost:8080/main/config to deploy on Proxmox VE.

• Global environment variables can be set in globals.json.

• container.stage.env is sourced for forked-repository deployments.

• .local files can be used to structure versioning; e.g. globals.local.json, container.local.env or 10-assistant.local.caddy

• run release: creates and configures a container.
• run main: configures an existing container.
• run snapshot: creates a snapshot leveraging Utils.snapshot.
• run rollback: rolls back configuration changes.

git clone --recurse-submodules, e.g., for Version-Controlled Mirroring.

• local/share/ can be used for persistence.

• Backup, Update and Rollback: See Self-Containment, which mirrors the system's architecture, implying lifecycle operations emerge from the principle itself.

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 container.env to your container's root directory (e.g. ./libs/apache):

IP=192.168.178.42
ID=42
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 Default.user(self)  # see base/roles/base/tasks/main.yml
  group Default.group(self) # each container is configured identically 
end

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

• Add to Monorepository and redeploy.

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

• The container can be tested locally by running ./local/run.sh [container]:

  Example: Apache