Deploying Phorge

Introduction

Phorge is a community-maintained fork of Phabricator, the comprehensive software development platform originally created by Facebook. It provides an integrated suite of tools for code hosting, project management, code review, bug tracking, and team collaboration. Phorge continues the development of Phabricator after its original maintenance ended, ensuring the platform remains updated and secure.

Built with PHP and backed by MySQL, Phorge offers a monolithic yet modular architecture where each application handles a specific aspect of the development workflow. From Diffusion (code hosting) to Differential (code review) to Maniphest (issue tracking), Phorge provides everything a development team needs in one cohesive platform.

Key highlights of Phorge:

Code Hosting (Diffusion): Host Git, Mercurial, and SVN repositories with web-based browsing
Code Review (Differential): Comprehensive pre-commit code review workflow
Issue Tracking (Maniphest): Flexible task and bug tracking with custom fields
Project Management: Workboards, milestones, and sprint planning
Wiki (Phriction): Collaborative documentation with version history
Chat (Conpherence): Built-in team messaging and discussions
Build Automation (Harbormaster): CI/CD integration and build management
File Storage (Files): Centralized file management and sharing
Authentication: LDAP, OAuth, SAML, and custom auth providers
Audit System: Post-commit code auditing workflow
100% Open Source: Community-driven development with Apache 2.0 license

This guide walks through deploying Phorge on Klutch.sh using Docker, configuring the database, and setting up the platform for production use.

Why Deploy Phorge on Klutch.sh

Deploying Phorge on Klutch.sh provides several advantages for your development team:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Phorge without complex orchestration. Push to GitHub and your platform deploys automatically.

Persistent Storage: Attach persistent volumes for your database, repositories, and file storage. Your code and data survive container restarts.

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

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on team size and repository count. Scale as your organization grows.

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

Custom Domains: Assign a custom domain to your Phorge instance for professional access.

Always-On Availability: Your development platform remains accessible 24/7 without managing infrastructure.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Phorge configuration
A MySQL or MariaDB database
Basic familiarity with Docker and PHP applications
(Optional) SMTP credentials for email notifications
(Optional) A custom domain for your Phorge instance

Understanding Phorge Architecture

Phorge consists of multiple integrated applications:

Diffusion: Repository hosting and browsing for Git, Mercurial, and SVN. Provides commit history, blame view, and repository management.

Differential: Pre-commit code review system with inline comments, revision updates, and approval workflows.

Maniphest: Task and issue tracking with custom fields, priorities, and project associations.

Phriction: Wiki system for team documentation with full revision history.

Harbormaster: Build automation and CI/CD integration with custom build plans.

Herald: Rules engine for automated actions based on events (commits, reviews, tasks).

Owners: Code ownership definitions for automatic reviewer assignment.

Conpherence: Team chat and discussion threads integrated with other applications.

Preparing Your Repository

To deploy Phorge on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

phorge-deploy/
├── Dockerfile
├── .dockerignore
├── phorge.conf
└── README.md

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM php:8.1-apache

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    libzip-dev \
    zip \
    unzip \
    libicu-dev \
    libfreetype6-dev \
    libjpeg62-turbo-dev \
    python3 \
    python3-pip \
    mercurial \
    subversion \
    procps \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd zip intl opcache

# Install APCu extension
RUN pecl install apcu && docker-php-ext-enable apcu

# Enable Apache modules
RUN a2enmod rewrite headers

WORKDIR /var/www

# Clone Phorge repositories
RUN git clone https://we.phorge.it/source/phorge.git && \
    git clone https://we.phorge.it/source/arcanist.git

# Create required directories
RUN mkdir -p /var/repo /var/tmp/phd /var/www/phorge/conf/local

# Set permissions
RUN chown -R www-data:www-data /var/www /var/repo /var/tmp/phd

# Configure Apache
COPY phorge.conf /etc/apache2/sites-available/000-default.conf

# PHP configuration
RUN echo "post_max_size = 128M" >> /usr/local/etc/php/conf.d/phorge.ini && \
    echo "upload_max_filesize = 128M" >> /usr/local/etc/php/conf.d/phorge.ini && \
    echo "memory_limit = 512M" >> /usr/local/etc/php/conf.d/phorge.ini && \
    echo "opcache.enable = 1" >> /usr/local/etc/php/conf.d/phorge.ini && \
    echo "apc.shm_size = 64M" >> /usr/local/etc/php/conf.d/phorge.ini

EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

CMD ["apache2-foreground"]

Apache Configuration

Create a phorge.conf file:

<VirtualHost *:80>
    ServerAdmin admin@example.com
    DocumentRoot /var/www/phorge/webroot

    RewriteEngine on
    RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]

    <Directory /var/www/phorge/webroot>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/phorge-error.log
    CustomLog ${APACHE_LOG_DIR}/phorge-access.log combined
</VirtualHost>

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Default	Description
`MYSQL_HOST`	Yes	-	MySQL server hostname
`MYSQL_USER`	Yes	-	MySQL username
`MYSQL_PASS`	Yes	-	MySQL password
`PHORGE_URI`	Yes	-	Base URL of your Phorge instance
`MAIL_ADAPTER`	No	-	Email adapter configuration

Deploying Phorge on Klutch.sh

Once your repository is prepared, follow these steps to deploy Phorge:

Provision MySQL Database

Phorge requires MySQL or MariaDB. Set up a database through Klutch.sh or an external provider. Phorge will create its own database schemas during setup.

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile phorge.conf .dockerignore
git commit -m "Initial Phorge deployment configuration"
git remote add origin https://github.com/yourusername/phorge-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “phorge” or “dev-platform”.

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 Phorge Dockerfile.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 80 (Apache’s default port)

Set Environment Variables

Add the following environment variables:

Variable	Value
`MYSQL_HOST`	Your MySQL server address
`MYSQL_USER`	Database username
`MYSQL_PASS`	Database password
`PHORGE_URI`	`https://your-app-name.klutch.sh`

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
`/var/repo`	50 GB	Git/Mercurial/SVN repositories
`/var/www/phorge/conf/local`	100 MB	Configuration files
`/var/tmp/phd`	5 GB	Daemon working directory

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 Phorge container
Provision an HTTPS certificate

Configure Phorge

After deployment, configure Phorge by running configuration commands:

./bin/config set mysql.host $MYSQL_HOST
./bin/config set mysql.user $MYSQL_USER
./bin/config set mysql.pass $MYSQL_PASS
./bin/config set phorge.base-uri $PHORGE_URI

Run Storage Upgrade

Initialize the database schemas:

./bin/storage upgrade --force

Access Phorge

Once configuration completes, access your Phorge instance at https://your-app-name.klutch.sh. Create your administrator account to begin setup.

Initial Setup and Configuration

Creating Admin Account

On first access:

Click “Create Admin Account”
Enter username, email, and password
Complete account verification
Access the administrator dashboard

Configuring Authentication

Set up authentication providers:

Username/Password: Built-in authentication
LDAP: Enterprise directory integration
OAuth: GitHub, Google, Facebook integration
SAML: Enterprise SSO support

Setting Up Email

Configure email for notifications:

Navigate to Config > Mail
Set SMTP or API-based mail adapter
Configure sender address
Test email delivery

Configuring Repositories

Set up Diffusion for code hosting:

Navigate to Diffusion
Create a new repository
Configure Git, Mercurial, or SVN backend
Set up SSH or HTTP access

Application Deep Dive

Differential (Code Review)

Configure code review workflows:

Reviewers: Assign required reviewers for changes
Build Plans: Integrate with CI/CD for automated testing
Landing: Configure how approved changes are landed

Maniphest (Task Tracking)

Set up issue tracking:

Custom Fields: Add fields specific to your workflow
Priorities: Define priority levels and SLAs
Projects: Organize tasks by project and milestone

Harbormaster (CI/CD)

Configure build automation:

Build Plans: Define build steps and conditions
Artifacts: Manage build outputs
Buildables: Connect to external CI systems

Herald (Automation)

Create automated rules:

Triggers: Define events that activate rules
Actions: Specify automated responses
Conditions: Set criteria for rule matching

Production Best Practices

Security Recommendations

Strong Authentication: Enable MFA for administrators
Access Control: Use projects to manage permissions
Audit Logging: Enable comprehensive audit trails
Regular Updates: Keep Phorge updated for security patches

Performance Optimization

Repository Caching: Enable opcache for better performance
Database Tuning: Optimize MySQL for your workload
Daemons: Configure background daemons for async processing
CDN: Consider CDN for static assets

Backup Strategy

Protect your development data:

Database Backups: Regular MySQL dumps
Repository Backups: Mirror repositories to secondary storage
Configuration Backups: Save configuration files
File Storage: Back up uploaded files and artifacts

Troubleshooting Common Issues

Database Connection Errors

Symptoms: Unable to connect to MySQL.

Solutions:

Verify MySQL host and credentials
Check network connectivity
Confirm MySQL user permissions
Review firewall rules

Repository Access Issues

Symptoms: Cannot clone or push to repositories.

Solutions:

Verify SSH key configuration
Check repository permissions
Review Diffusion settings
Confirm daemon is running

Daemon Not Running

Symptoms: Background tasks not processing.

Solutions:

Start the phd daemon manually
Check daemon log files
Verify daemon configuration
Ensure proper permissions

Additional Resources

Conclusion

Deploying Phorge on Klutch.sh gives you a comprehensive development platform with automatic builds, persistent storage, and secure HTTPS access. The integrated suite of tools covers the entire development lifecycle from code hosting to project management to code review.

With its modular architecture and extensive customization options, Phorge adapts to teams of all sizes and development methodologies. Whether you’re a small team looking for an all-in-one solution or a large organization needing enterprise features, Phorge on Klutch.sh provides the foundation for effective software development collaboration.