Chantal

User Guide

  • Installation
    • Requirements
    • Installation Steps
      • 1. Clone the Repository
      • 2. Install in Development Mode
      • 3. Verify Installation
    • Dependencies
    • Database Setup
      • SQLite (Development)
      • PostgreSQL (Production)
    • Next Steps
  • Quick Start
    • 1. Initialize Database
    • 2. Configure Repositories
    • 3. List Configured Repositories
    • 4. Sync Repository
    • 5. Check for Updates
    • 6. Create Snapshot
    • 7. Publish Repository
    • Next Steps
  • CLI Commands
    • Global Options
    • Configuration File Priority
    • Database Management
      • chantal db init
      • chantal db status
      • chantal db current
      • chantal db upgrade
      • chantal db history
    • Repository Management
      • chantal repo list
      • chantal repo show
      • chantal repo sync
      • chantal repo check-updates
      • chantal repo history
    • Snapshot Management
      • chantal snapshot list
      • chantal snapshot create
      • chantal snapshot content
      • chantal snapshot diff
      • chantal snapshot delete
    • Content Management
      • chantal content list
      • chantal content search
      • chantal content show
    • Publishing
      • chantal publish repo
      • chantal publish snapshot
      • chantal publish list
      • chantal publish unpublish
    • Storage Pool Management
      • chantal pool stats
      • chantal pool orphaned
      • chantal pool cleanup
      • chantal pool verify
      • chantal pool missing
    • Statistics & Database
      • chantal stats
      • chantal db stats
      • chantal db verify
      • chantal db cleanup
    • Output Formats
  • Views (Virtual Repositories)
    • What are Views?
    • Use Cases
      • 1. Combining RHEL Channels
      • 2. Mixing RHEL + EPEL
      • 3. Custom Application Stacks
    • Configuration
      • Location
      • Format
      • Requirements
      • Example Configuration
    • CLI Commands
      • List Views
      • Show View Details
      • Publish View (Latest/Rolling)
    • View Snapshots
      • Create View Snapshot (Atomic Freeze)
      • Publish View Snapshot
      • Show Snapshot Content (Compliance/Audit)
    • Workflows
      • Workflow 1: Rolling Release (Development)
      • Workflow 2: Frozen Baselines (Production)
      • Workflow 3: Compliance/Audit
      • Workflow 4: Automated Monthly Compliance Reports
    • Important Design Decisions
      • 1. NO Deduplication
      • 2. Repository Order Matters
      • 3. View Snapshots are Atomic
      • 4. Hardlink-based Publishing
    • Client Configuration Examples
      • Example 1: Development (Rolling Release)
      • Example 2: Production (Frozen Baseline)
      • Example 3: Testing New Baseline
    • Troubleshooting
      • View shows 0 packages
      • View snapshot creation fails
      • Published view doesn’t update
      • Repository not found in view
      • View type mismatch
    • Best Practices
    • Migration from Pulp/Katello
      • Pulp “Composite Content Views” → Chantal “Views”
    • Technical Details
      • Database Models
      • Storage Structure
    • Future Enhancements
  • Workflows
    • Patch Management Workflow
      • Step 1: Initial Setup
      • Step 2: Create Monthly Baseline
      • Step 3: Monthly Update Cycle
      • Step 4: Promote to Production
    • Development Environment Workflow
      • Setup
      • Working with Snapshots
    • Air-Gapped Environment Workflow
      • Phase 1: Online System (Internet-Connected)
      • Phase 2: Offline System (Air-Gapped)
    • RHEL Subscription Workflow
      • Setup RHEL Subscription
    • Selective Mirroring Workflow
      • Example: Only Mirror Web Server Packages
    • Multi-Architecture Workflow
      • Configuration
      • Sync Both Architectures
    • Scheduled Sync Workflow
      • Cron Example
      • Systemd Timer Example
    • Disaster Recovery Workflow
      • Backup
      • Restore

Configuration

  • Configuration Overview
    • Configuration File Structure
    • Configuration File Priority
    • Development vs. Production
      • Production Setup
      • Development Setup
    • Database Configuration
      • SQLite (Development/Testing)
      • PostgreSQL (Production)
    • Storage Configuration
      • Storage Paths
      • Directory Permissions
    • Proxy Configuration
      • Global Proxy
      • Per-Repository Proxy Override
      • No Proxy for Specific Repository
    • SSL/TLS Configuration
      • Global SSL Settings
      • Per-Repository SSL (e.g., RHEL CDN)
    • Including Additional Configuration Files
    • Configuration Validation
    • Environment Variables
    • Best Practices
  • Repository Configuration
    • Basic Repository Configuration
    • Repository Types
      • RPM Repositories
      • Helm Repositories
      • Alpine APK Repositories
      • APT Repositories
      • PyPI Repositories (Future)
    • Advanced Options
      • Version Retention Policy
      • Repository Tags
      • Custom Publishing Paths
    • Per-Repository Settings
      • Metadata Cache Override
      • Proxy Override
      • SSL/TLS Override
      • HTTP Headers
    • Repository Organization
      • Single File Configuration
      • Multi-File Configuration
    • Real-World Examples
      • RHEL 9 with Subscription
      • Rocky Linux 9
      • EPEL 9 with Selective Mirroring
      • CentOS Stream 9
      • Helm Charts - Ingress NGINX
      • Helm Charts - Bitnami (Selective)
      • Helm Charts - Private Repository
      • Alpine Linux 3.19 (Main + Community)
      • Alpine Linux Edge (Rolling Release)
      • Alpine Linux - Container Base (Selective)
    • Validation
    • Best Practices
  • Package Filters
    • Filter Types
    • Pattern-Based Filtering
      • Include Patterns
      • Exclude Patterns
      • Combined Example
    • Metadata Filters
      • Architecture Filtering
      • Size Filtering
      • Build Time Filtering
    • RPM-Specific Filters
      • Exclude Source RPMs
      • Group Filtering
      • License Filtering
    • Post-Processing
      • Only Latest Version
      • Only Latest N Versions
    • Complete Examples
      • Example 1: Web Server Packages Only
      • Example 2: Minimal Base System
      • Example 3: Security Updates Only
      • Example 4: Development Tools
    • Filter Debugging
      • Dry-Run Mode
      • Verbose Output
    • Best Practices
  • SSL/TLS and Authentication
    • Overview
    • Global SSL Configuration
    • Per-Repository SSL Configuration
    • SSL Options
      • CA Bundle
      • Client Certificate
      • Client Key
      • Verify Server Certificate
    • RHEL Subscription Setup
      • Method 1: Using subscription-manager (Recommended)
      • Method 2: Manual Certificate Download
      • Method 3: Shared Entitlement (Development)
    • Complete RHEL Configuration Example
    • Self-Signed Certificates
      • Option 1: Add to System Trust Store (Recommended)
      • Option 2: Custom CA Bundle
      • Option 3: Disable Verification (Not Recommended)
    • Troubleshooting
      • Certificate Errors
      • Client Certificate Errors
      • Permission Errors
      • Check Certificate Validity
    • Security Best Practices

Architecture

  • Architecture Overview
    • Core Principles
    • System Architecture
    • Components
      • CLI Layer
      • Core Layer
        • Configuration Management
        • Storage Manager
        • Database Manager
      • Plugin Layer
        • Sync Plugins
        • Publisher Plugins
    • Data Flow
      • Sync Workflow
      • Publish Workflow
    • Technology Stack
      • Runtime
      • Development
      • Database
    • Design Decisions
      • Why Content-Addressed Storage?
      • Why Database for Metadata?
      • Why Hardlinks for Publishing?
    • Performance Characteristics
      • Sync Performance
      • Storage Efficiency
      • Database Performance
    • Extensibility Points
      • Adding Repository Types
      • Adding Filter Types
      • Adding Output Formats
    • Security Considerations
    • Future Enhancements
  • Content-Addressed Storage
    • Overview
    • Storage Structure
      • 2-Level Directory Hierarchy
      • Why 2 Levels?
    • Deduplication
      • Automatic Deduplication
      • Cross-Repository Deduplication
    • Database Integration
      • Package Model
      • Junction Table
    • Hardlink-Based Publishing
    • Storage Operations
      • Add Package
      • Create Hardlink
      • Verify Pool Integrity
      • Cleanup Orphaned Files
    • Storage Statistics
      • Pool Stats
      • Deduplication Stats
    • Advantages
    • Limitations
    • Best Practices
  • Database Schema
    • Overview
    • Core Models
      • Package
      • Repository
      • Snapshot
      • View
      • ViewSnapshot
      • SyncHistory
    • Junction Tables
      • repository_packages
      • snapshot_packages
      • view_repositories
      • view_snapshot_snapshots
    • Indexes
    • Database Migrations
      • Migration Files
      • Run Migrations
    • Example Queries
      • Find all packages in repository
      • Find all repositories containing a package
      • Create snapshot
      • Find packages added between snapshots
    • Database Backends
      • SQLite (Development)
      • PostgreSQL (Production)
    • Database Size Estimates
    • Maintenance
      • Vacuum (SQLite)
      • Analyze (PostgreSQL)
      • Cleanup Orphaned Packages
    • Schema Diagram
  • Plugin System
    • Overview
    • Plugin Types
      • Sync Plugin
      • Publisher Plugin
    • Available Plugins
      • RPM Plugin
      • DEB/APT Plugin
      • PyPI Plugin
    • Plugin Registration
    • Creating a Custom Plugin
      • 1. Implement Sync Plugin
      • 2. Implement Publisher Plugin
      • 3. Register Plugin
      • 4. Add Configuration Support
    • Plugin Lifecycle
      • Sync Lifecycle
      • Publish Lifecycle
    • Plugin Helpers
      • StorageManager
      • HTTP Client
      • Filter Engine
    • Testing Plugins
      • Unit Tests
      • Integration Tests
    • Best Practices
    • Future Enhancements

Plugins

  • Plugins Overview
    • What are Plugins?
    • Available Plugins
    • Plugin Architecture
    • How Plugins Work
      • Sync Plugin Workflow
      • Publisher Plugin Workflow
    • Plugin Types
      • RPM Plugin
      • APT/DEB Plugin
      • PyPI Plugin (Planned)
    • Creating Custom Plugins
    • Plugin Configuration
    • Plugin Registry
    • Plugin Best Practices
    • Further Reading
  • RPM Plugin
    • Overview
    • Features
    • Configuration
      • Basic RPM Repository
      • With Filters
      • With Custom Compression
      • RHEL with Client Certificates
    • Repository Modes
      • Mirror Mode (Default)
      • Filtered Mode
      • Hosted Mode
    • How It Works
      • Sync Process
        • 1. Fetch repomd.xml
        • 2. Download Metadata
        • 3. Parse Packages
        • 4. Apply Filters (Filtered Mode Only)
        • 5. Download Packages
        • 6. Update Database
      • Publish Process
        • 1. Query Packages
        • 2. Create Directory Structure
        • 3. Create Package Hardlinks
        • 4. Publish Metadata
        • 5. Updateinfo Filtering (Filtered Mode)
        • 6. Result
    • Metadata Files
      • repomd.xml
      • primary.xml.gz
    • Compression Support
      • Supported Formats
      • Auto-Detection
      • Configuration
      • Compression Behavior
      • Performance Characteristics
      • Testing
      • Examples
    • RPM-Specific Filters
      • Exclude Source RPMs
      • Group Filtering
      • License Filtering
    • Supported Distributions
      • Red Hat Enterprise Linux (RHEL)
      • CentOS Stream
      • Fedora
      • EPEL (Extra Packages for Enterprise Linux)
      • Rocky Linux
      • AlmaLinux
    • Troubleshooting
      • Metadata Not Found
      • Checksum Mismatch
      • No Packages After Filtering
    • Future Enhancements
  • APT Plugin
    • Overview
    • Features
    • Configuration
      • Basic APT Repository
      • Multi-Component Repository
      • Mirror Mode (Exact Copy)
      • With Authentication
    • APT-Specific Options
      • Required Options
      • Optional Options
    • Publishing
      • Publish Latest Repository State
      • Publish Snapshot
      • Unpublish
    • Directory Structure
      • Standard APT Repository Layout
      • Content-Addressed Storage Pool
    • Repository Modes
      • MIRROR Mode
      • FILTERED Mode
    • Workflow Examples
      • Example 1: Mirror Ubuntu LTS
      • Example 2: Docker CE Mirror
    • Troubleshooting
      • InRelease file not found
      • Architecture not found
      • Component not available
      • Source packages missing
    • Advanced Topics
      • Dependency Resolution
      • Multi-Arch Support
      • Package Priorities
      • Sections
    • Integration with Other Tools
      • apt-mirror Replacement
      • aptly Comparison
    • Performance
    • See Also
  • Helm Plugin
    • Overview
    • Features
    • Repository Modes
      • Mirror Mode (Default)
      • Dynamic Generation Mode (Fallback)
    • Configuration
      • Basic Helm Repository
      • With Filters
      • With Authentication
    • How It Works
      • Sync Process
      • Publish Process
    • Chart Filtering
      • Pattern Filters
      • Version Filtering
    • Common Use Cases
      • Mirror Official Kubernetes Charts
      • Mirror Bitnami Charts (Selective)
      • Mirror Harbor Registry
      • Private Chart Repository
    • Publishing Helm Repositories
      • Publish Latest Repository
      • Publish Snapshot
      • Configure Helm Client
      • Configure Helm with Snapshot
    • Chart Metadata
    • Troubleshooting
      • Charts Not Syncing
      • Publishing Issues
      • Client Certificate Issues
    • Best Practices
    • Integration with CI/CD
      • GitOps Workflow
      • Jenkins Pipeline
    • Further Reading
  • Alpine APK Plugin
    • Overview
    • Features
    • Repository Modes
      • Mirror Mode (Default)
      • Dynamic Generation Mode (Fallback)
    • Configuration
      • Basic Alpine Repository
      • With Filters
      • Multiple Architectures
    • How It Works
      • Sync Process
      • Publish Process
    • Package Filtering
      • Pattern Filters
      • Version Filtering
    • Common Use Cases
      • Mirror Complete Alpine Branch
      • Mirror Community Repository
      • Mirror Edge (Rolling Release)
      • Selective Mirroring (Container Base)
    • Publishing Alpine Repositories
      • Publish Latest Repository
      • Publish Snapshot
      • Configure Alpine Linux Client
      • Configure Alpine with Snapshot
    • Package Metadata
    • Alpine-Specific Features
      • Version Format
      • Repository Types
      • Alpine Branches
    • Troubleshooting
      • APKINDEX Not Found
      • SHA1 Checksum Warnings
      • No Packages After Filtering
      • Architecture Mismatch
    • Integration with Docker
      • Alpine Base Image Builds
      • Multi-Architecture Builds
    • Best Practices
    • Further Reading
  • Creating Custom Plugins
    • Overview
    • Prerequisites
    • Step 1: Create Plugin Files
    • Step 2: Implement Sync Plugin
      • Basic Structure
      • Helper Methods
        • HTTP Client
        • Download File
    • Step 3: Implement Publisher Plugin
      • Basic Structure
      • Metadata Generation Example
    • Step 4: Register Plugin
    • Step 5: Add Configuration Support
    • Step 6: Write Tests
    • Example: Simple HTTP Archive Plugin
    • Best Practices
    • Testing Your Plugin
    • Contributing Your Plugin

API Reference

  • API Reference
    • Core Modules
      • Configuration
        • ApkConfig
        • AptConfig
        • AuthConfig
        • CacheConfig
        • ConfigLoader
        • DatabaseConfig
        • DebFilterConfig
        • DownloadConfig
        • FilterConfig
        • GenericMetadataFilterConfig
        • GlobalConfig
        • ListFilterConfig
        • MetadataConfig
        • PatternFilterConfig
        • PostProcessingConfig
        • ProxyConfig
        • RepositoryConfig
        • RetentionConfig
        • RpmFilterConfig
        • SSLConfig
        • ScheduleConfig
        • SizeFilterConfig
        • StorageConfig
        • TimeFilterConfig
        • ViewConfig
        • create_example_config()
        • load_config()
      • Storage
        • StorageManager
    • Database Models
      • Base
        • Base.metadata
        • Base.registry
      • ContentItem
        • ContentItem.arch
        • ContentItem.content_metadata
        • ContentItem.content_type
        • ContentItem.created_at
        • ContentItem.epoch
        • ContentItem.filename
        • ContentItem.id
        • ContentItem.name
        • ContentItem.nevra
        • ContentItem.pool_path
        • ContentItem.reference_count
        • ContentItem.release
        • ContentItem.repositories
        • ContentItem.sha256
        • ContentItem.size_bytes
        • ContentItem.snapshots
        • ContentItem.version
      • Repository
        • Repository.content_items
        • Repository.created_at
        • Repository.enabled
        • Repository.feed
        • Repository.id
        • Repository.last_sync_at
        • Repository.last_sync_status
        • Repository.latest_path
        • Repository.mode
        • Repository.name
        • Repository.repo_id
        • Repository.repository_files
        • Repository.snapshots
        • Repository.snapshots_path
        • Repository.sync_history
        • Repository.type
        • Repository.updated_at
      • RepositoryFile
        • RepositoryFile.created_at
        • RepositoryFile.file_category
        • RepositoryFile.file_metadata
        • RepositoryFile.file_type
        • RepositoryFile.id
        • RepositoryFile.original_path
        • RepositoryFile.pool_path
        • RepositoryFile.repositories
        • RepositoryFile.sha256
        • RepositoryFile.size_bytes
        • RepositoryFile.snapshots
        • RepositoryFile.updated_at
      • RepositoryMode
        • RepositoryMode.FILTERED
        • RepositoryMode.HOSTED
        • RepositoryMode.MIRROR
      • Snapshot
        • Snapshot.content_items
        • Snapshot.created_at
        • Snapshot.description
        • Snapshot.id
        • Snapshot.is_published
        • Snapshot.name
        • Snapshot.package_count
        • Snapshot.published_path
        • Snapshot.repository
        • Snapshot.repository_files
        • Snapshot.repository_id
        • Snapshot.total_size_bytes
      • SyncHistory
        • SyncHistory.bytes_downloaded
        • SyncHistory.completed_at
        • SyncHistory.duration_seconds
        • SyncHistory.error_message
        • SyncHistory.id
        • SyncHistory.packages_added
        • SyncHistory.packages_removed
        • SyncHistory.packages_updated
        • SyncHistory.repository
        • SyncHistory.repository_id
        • SyncHistory.snapshot
        • SyncHistory.snapshot_id
        • SyncHistory.started_at
        • SyncHistory.status
      • View
        • View.created_at
        • View.description
        • View.id
        • View.is_published
        • View.name
        • View.published_at
        • View.published_path
        • View.repo_type
        • View.updated_at
        • View.view_repositories
        • View.view_snapshots
      • ViewRepository
        • ViewRepository.added_at
        • ViewRepository.id
        • ViewRepository.order
        • ViewRepository.repository
        • ViewRepository.repository_id
        • ViewRepository.view
        • ViewRepository.view_id
      • ViewSnapshot
        • ViewSnapshot.created_at
        • ViewSnapshot.description
        • ViewSnapshot.id
        • ViewSnapshot.is_published
        • ViewSnapshot.name
        • ViewSnapshot.package_count
        • ViewSnapshot.published_at
        • ViewSnapshot.published_path
        • ViewSnapshot.snapshot_ids
        • ViewSnapshot.total_size_bytes
        • ViewSnapshot.view
        • ViewSnapshot.view_id
    • Plugins
      • Base Plugins
      • RPM Plugin
      • APT Plugin
      • Helm Plugin
      • Alpine APK Plugin
    • CLI Commands
Chantal
  • Search

© Copyright 2026, Simon Lauger.

Built with Sphinx using a theme provided by Read the Docs.