Deploying Pagure

Introduction

Pagure is a Git-centered forge, a web application for hosting Git repositories along with issue tracking, pull requests, and project management features. Developed by the Fedora Project, Pagure provides a lightweight alternative to platforms like GitHub and GitLab while remaining completely open source.

Built with Python and Flask, Pagure emphasizes simplicity and Git-native workflows. It stores issues and pull request metadata directly in Git repositories, making your entire project history portable and version-controlled.

Key highlights of Pagure:

• Git-Native Storage: Issues, pull requests, and metadata are stored in Git, making everything portable and version-controlled
• Pull Request Workflow: Full-featured pull request system with code review, comments, and merge capabilities
• Issue Tracking: Built-in issue tracker with labels, milestones, and custom fields
• Project Forking: Fork projects easily and contribute back through pull requests
• Group Management: Organize users into groups with configurable permissions
• API Access: Comprehensive REST API for automation and integrations
• Federated Design: Projects can be mirrored and federated across instances
• Markdown Support: Rich text formatting in issues, comments, and documentation
• SSH and HTTPS Access: Clone and push via SSH keys or HTTPS authentication
• Webhook Support: Trigger external services on repository events
• Open Source: Licensed under GPL-2.0, developed by the Fedora community

This guide walks through deploying Pagure on Klutch.sh using Docker, configuring the application for production use, and setting up persistent storage for your repositories and data.

Why Deploy Pagure on Klutch.sh

Deploying Pagure on Klutch.sh provides several advantages for your development workflow:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Pagure without complex orchestration. Push to GitHub, and your forge deploys automatically.

Full Data Ownership: Host your repositories on your own infrastructure with complete control over access and policies.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your code repositories.

Persistent Storage: Attach persistent volumes for your Git repositories and database. Your code survives container restarts and redeployments.

GitHub Integration: Connect your configuration repository directly from GitHub for easy deployment management.

Custom Domains: Assign a professional domain to your Pagure instance for team collaboration.

Environment Variable Management: Securely store database credentials and secret keys through Klutch.sh’s environment variable system.

Prerequisites

Before deploying Pagure on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Pagure configuration
• Basic familiarity with Docker and containerization concepts
• A PostgreSQL database (can be deployed on Klutch.sh or use an external service)
• A Redis instance for caching and background tasks

Understanding Pagure Architecture

Pagure consists of several components:

Web Application: The Flask-based frontend handling HTTP requests, rendering pages, and serving the API.

Git Backend: Manages Git repository operations including clones, pushes, and access control.

Worker Processes: Background workers handle tasks like sending emails, updating caches, and processing webhooks.

Database: PostgreSQL stores user accounts, access control, and non-Git metadata.

Redis: Provides caching and message queuing for background tasks.

Git Repositories: The actual Git repositories stored on persistent storage.

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for Pagure deployment.

Repository Structure

pagure-deploy/
├── Dockerfile
├── pagure.cfg
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM fedora:latest

# Install dependencies
RUN dnf install -y \
    python3-pip \
    python3-devel \
    git \
    redis \
    postgresql-devel \
    gcc \
    libffi-devel \
    && dnf clean all

# Install Pagure
RUN pip3 install pagure

# Create necessary directories
RUN mkdir -p /srv/git/repositories \
    /srv/git/remotes \
    /srv/git/attachments \
    /etc/pagure

# Copy configuration
COPY pagure.cfg /etc/pagure/pagure.cfg

# Set environment variables
ENV PAGURE_CONFIG=/etc/pagure/pagure.cfg

# Expose the web interface port
EXPOSE 5000

# Start Pagure
CMD ["python3", "-m", "pagure.run_app", "--host=0.0.0.0", "--port=5000"]

Creating the Configuration File

Create a pagure.cfg file:

import os

# Base configuration
SECRET_KEY = os.environ.get('SECRET_KEY', 'change-me-in-production')
SALT_EMAIL = os.environ.get('SALT_EMAIL', 'change-me-too')

# Database configuration
DB_URL = os.environ.get('DATABASE_URL', 'postgresql://pagure:password@localhost/pagure')

# Git repository paths
GIT_FOLDER = '/srv/git/repositories'
REMOTE_GIT_FOLDER = '/srv/git/remotes'
ATTACHMENTS_FOLDER = '/srv/git/attachments'

# Application URL
APP_URL = os.environ.get('APP_URL', 'https://pagure.example.com')

# Redis configuration
REDIS_HOST = os.environ.get('REDIS_HOST', 'localhost')
REDIS_PORT = int(os.environ.get('REDIS_PORT', 6379))

# Email configuration
SMTP_SERVER = os.environ.get('SMTP_SERVER', 'localhost')
FROM_EMAIL = os.environ.get('FROM_EMAIL', 'pagure@example.com')

# Features
ENABLE_TICKETS = True
ENABLE_DOCS = True
ENABLE_GROUP_MNGT = True
ALLOW_PROJECT_DOWAIT = True

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Deploying Pagure on Klutch.sh

Generate Secret Keys

Before deployment, generate secure secret keys:

python3 -c "import secrets; print(secrets.token_hex(32))"

Generate two separate keys: one for SECRET_KEY and one for SALT_EMAIL.

Set Up PostgreSQL Database

Deploy a PostgreSQL instance on Klutch.sh or use an external database service. Note the connection URL for configuration.

Set Up Redis

Deploy a Redis instance on Klutch.sh for caching and background task processing.

Push Your Repository to GitHub

Initialize your repository and push to GitHub with your Dockerfile and configuration files.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “pagure” or “git-forge”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Pagure Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 5000

Set Environment Variables

Add the following environment variables:

Variable	Value
SECRET_KEY	Your generated secret key
SALT_EMAIL	Your generated email salt
DATABASE_URL	PostgreSQL connection string
REDIS_HOST	Your Redis host
APP_URL	https://your-app-name.klutch.sh

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/srv/git/repositories	50+ GB	Git repositories
/srv/git/attachments	10 GB	Issue and PR attachments

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Pagure container
• Provision an HTTPS certificate

Access Pagure

Once deployment completes, access your Pagure instance at https://your-app-name.klutch.sh and create your first project.

Initial Setup

Creating an Admin User

After deployment, create your first admin user through the command line or by accessing the registration page if enabled.

Configuring Projects

1. Log in with your admin account
2. Create a new project from the dashboard
3. Initialize or push an existing Git repository
4. Configure project settings, collaborators, and permissions

Managing Repositories

Cloning Repositories

Clone repositories using HTTPS:

git clone https://your-pagure-instance/project-name.git

Pushing Changes

Push changes to your Pagure instance after configuring authentication:

git push origin main

Additional Resources

• Pagure Official Repository
• Pagure Documentation
• Pagure Issue Tracker
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Pagure on Klutch.sh gives you a powerful, self-hosted Git forge with full control over your source code and development workflow. The combination of Pagure’s Git-native approach and Klutch.sh’s deployment simplicity means you can focus on building software rather than managing infrastructure.

With support for pull requests, issue tracking, and group management, Pagure scales from personal projects to team collaboration. The Git-based storage for metadata ensures your project history remains portable and version-controlled.