Deploying QPixel

Introduction

QPixel is a free, open-source Q&A platform that powers the Codidact network, providing a community-driven alternative to proprietary Q&A sites. Built with Ruby on Rails, QPixel offers a comprehensive feature set for building knowledge-sharing communities with questions, answers, voting, reputation systems, and moderation tools.

Designed with community governance in mind, QPixel addresses many concerns that led to the creation of Codidact as an alternative to Stack Exchange. The platform emphasizes transparency, community control, and flexibility in how communities can operate.

Key highlights of QPixel:

• Q&A Format: Questions, answers, and comments with markdown support
• Voting System: Upvotes and downvotes with customizable scoring
• Reputation System: Earned privileges based on community participation
• Multiple Categories: Support for different post types (Q&A, articles, blog posts)
• Moderation Tools: Flags, close votes, deletion, and review queues
• Tag System: Organize content with hierarchical tagging
• Search Functionality: Full-text search across all content
• User Profiles: Detailed user profiles with activity history
• Notifications: Real-time notifications for relevant activity
• Multi-Community: Host multiple communities on a single installation
• Customizable: Extensive theming and configuration options
• Open Source: Licensed under AGPL-3.0 with active development

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

Why Deploy QPixel on Klutch.sh

Deploying QPixel on Klutch.sh provides several advantages for hosting Q&A communities:

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

Persistent Storage: Attach persistent volumes for your database, uploads, and configuration. Your community content and user data survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access for your community members.

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

Scalable Resources: Allocate CPU and memory based on community size and activity. Scale as your community grows.

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

Custom Domains: Assign a custom domain to your QPixel instance for a professional community presence.

Always-On Availability: Your Q&A platform remains accessible 24/7 for community members worldwide.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your QPixel configuration
• Basic familiarity with Docker and Ruby on Rails concepts
• A MySQL or MariaDB database (can be provisioned through Klutch.sh)
• A Redis instance for caching and background jobs
• SMTP credentials for email notifications
• (Optional) A custom domain for your community

Understanding QPixel Architecture

QPixel is built on the Ruby on Rails stack:

Rails Application: The core application handles HTTP requests, business logic, and database operations using the MVC pattern.

MySQL/MariaDB Database: Stores all persistent data including posts, users, votes, and community configuration.

Redis: Handles caching, session storage, and serves as the backend for Sidekiq background jobs.

Sidekiq Workers: Background job processing for emails, notifications, and asynchronous tasks.

Asset Pipeline: Compiled CSS and JavaScript assets served by the Rails application.

File Uploads: User-uploaded images and attachments stored on the filesystem or object storage.

Preparing Your Repository

To deploy QPixel on Klutch.sh, create a GitHub repository with your deployment configuration.

Repository Structure

qpixel-deploy/
├── Dockerfile
├── docker-entrypoint.sh
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ruby:3.1-slim

# Install dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libmariadb-dev \
    nodejs \
    npm \
    git \
    imagemagick \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Clone QPixel repository
RUN git clone https://github.com/codidact/qpixel.git .

# Install Ruby dependencies
RUN bundle install --deployment --without development test

# Install Node dependencies and compile assets
RUN npm install
RUN bundle exec rails assets:precompile RAILS_ENV=production

# Copy entrypoint script
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

# Create necessary directories
RUN mkdir -p tmp/pids tmp/sockets log public/uploads

# Expose the application port
EXPOSE 3000

ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]

Creating the Entrypoint Script

Create a docker-entrypoint.sh file:

#!/bin/bash
set -e

# Wait for database to be ready
until bundle exec rails db:version 2>/dev/null; do
  echo "Waiting for database..."
  sleep 2
done

# Run migrations
bundle exec rails db:migrate

# Execute the main command
exec "$@"

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
tmp/
log/
node_modules/

Environment Variables Reference

Variable	Required	Description
DATABASE_URL	Yes	MySQL connection string
REDIS_URL	Yes	Redis connection string
SECRET_KEY_BASE	Yes	Rails secret key for sessions
RAILS_ENV	Yes	Set to production
SMTP_HOST	Yes	SMTP server hostname
SMTP_PORT	Yes	SMTP server port
SMTP_USER	Yes	SMTP username
SMTP_PASSWORD	Yes	SMTP password
SMTP_FROM	Yes	Default from email address

Deploying QPixel on Klutch.sh

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

Generate Your Secret Key

Generate a secure Rails secret key:

rails secret

Or use OpenSSL:

openssl rand -hex 64

Save this key for environment variable configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile docker-entrypoint.sh .dockerignore README.md
git commit -m "Initial QPixel deployment configuration"
git remote add origin https://github.com/yourusername/qpixel-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 “qpixel” or “qa-community”.

Provision Required Services

Before deploying QPixel, ensure you have:

• A MySQL or MariaDB database instance
• A Redis instance

Create a New App

Within your project, create a new app. Connect your GitHub account and select the repository containing your QPixel Dockerfile.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

In the environment variables section, add:

Variable	Value
DATABASE_URL	mysql2://user:password@host:3306/qpixel
REDIS_URL	redis://host:6379/0
SECRET_KEY_BASE	Your generated secret key
RAILS_ENV	production
SMTP_HOST	Your SMTP server
SMTP_PORT	587
SMTP_USER	Your SMTP username
SMTP_PASSWORD	Your SMTP password
SMTP_FROM	noreply@yourdomain.com

Attach Persistent Volumes

Add volumes for data persistence:

Mount Path	Recommended Size	Purpose
/app/public/uploads	10 GB	User uploaded images and files
/app/log	1 GB	Application logs

Deploy Your Application

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

• Build the container image
• Run database migrations
• Start the Rails server
• Provision an HTTPS certificate

Create Initial Admin Account

After deployment, access the Rails console to create an admin:

bundle exec rails console
User.create(email: 'admin@example.com', password: 'secure_password', is_admin: true)

Access QPixel

Once deployment completes, access your QPixel instance at https://your-app-name.klutch.sh.

Initial Setup and Configuration

Creating Your First Community

After logging in as admin:

1. Navigate to the admin panel
2. Click Create Community
3. Configure community name, description, and URL slug
4. Set up initial categories (Q&A, Meta, etc.)
5. Configure voting and reputation thresholds

Configuring Categories

QPixel supports multiple post types:

Category Type	Purpose
Q&A	Traditional question and answer format
Articles	Long-form content without the Q&A format
Meta	Community governance discussions
Blog	Official community announcements

Setting Up Moderation

Configure moderation tools:

1. Set up privilege thresholds for voting, editing, closing
2. Configure close reasons
3. Set up review queues
4. Add moderators and trusted users

Production Best Practices

Security Recommendations

• Secret Key Protection: Never commit secret keys to version control
• Database Security: Use strong passwords and encrypted connections
• Input Validation: QPixel handles this, but keep dependencies updated
• Rate Limiting: Configure rate limits to prevent abuse
• Regular Updates: Keep QPixel and dependencies updated

Performance Optimization

• Redis Caching: Properly configure Redis for fragment caching
• Database Indexes: Ensure proper indexes for large communities
• Asset Caching: Configure CDN for static assets
• Sidekiq Workers: Scale workers based on job volume

Backup Strategy

1. Database Backups: Regular MySQL dumps
2. Uploads: Back up the /app/public/uploads directory
3. Configuration: Document custom settings and theme changes

Troubleshooting Common Issues

Database Connection Errors

Symptoms: Application fails to start with database errors.

Solutions:

• Verify DATABASE_URL format and credentials
• Ensure MySQL server is accessible
• Check database user permissions

Asset Compilation Failures

Symptoms: Missing styles or JavaScript errors.

Solutions:

• Ensure Node.js is available during build
• Check for JavaScript errors in compilation
• Verify asset pipeline configuration

Email Delivery Issues

Symptoms: Users don’t receive notifications.

Solutions:

• Verify SMTP credentials
• Check spam folders
• Review mail logs for errors

Additional Resources

• Codidact Network
• QPixel GitHub Repository
• Codidact Meta Community
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying QPixel on Klutch.sh gives you a powerful, self-hosted Q&A platform with automatic builds, persistent storage, and secure HTTPS access. The combination of QPixel’s community-focused features and Klutch.sh’s deployment simplicity means you can focus on building your community rather than managing infrastructure.

With support for multiple communities, flexible moderation, and proven scalability from the Codidact network, QPixel handles everything from small topic-specific communities to large knowledge bases. The open governance model ensures your community remains in control of its own destiny.

Whether you’re building an internal knowledge base, a customer support community, or a topic-focused Q&A site, QPixel on Klutch.sh provides the foundation for sustainable community growth.