Deploying Octobox

Introduction

Octobox is an open-source GitHub notification management tool that helps developers and teams stay on top of their GitHub notifications. It provides an email-like inbox interface for organizing, triaging, and managing the constant stream of notifications from issues, pull requests, and discussions.

Built with Ruby on Rails, Octobox transforms the often overwhelming GitHub notification experience into a manageable workflow. With features like filtering, starring, muting, and automatic archiving, Octobox helps you focus on what matters and never miss important updates.

Key highlights of Octobox:

• Inbox Interface: Email-like experience for notifications
• Smart Filtering: Filter by repository, type, reason, and more
• Keyboard Shortcuts: Efficient keyboard-driven navigation
• Auto-Archive: Automatically archive resolved issues and merged PRs
• Starring and Muting: Prioritize or silence specific notifications
• Search: Full-text search across all notifications
• Multi-Account: Support for multiple GitHub accounts
• Sync: Real-time synchronization with GitHub
• API Access: RESTful API for integrations
• Open Source: AGPL-3.0 license with active development

This guide walks through deploying Octobox on Klutch.sh using Docker.

Why Deploy Octobox on Klutch.sh

Deploying Octobox on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the Rails deployment automatically.

Persistent Storage: Attach persistent volumes for your notification data.

HTTPS by Default: Automatic SSL certificates for secure access.

GitHub Integration: OAuth authentication with your GitHub account.

Scalable Resources: Allocate CPU and memory based on team size.

Environment Variable Management: Securely store OAuth credentials.

Custom Domains: Use your own domain for your notification manager.

Always-On Availability: Your notification inbox remains accessible 24/7.

Prerequisites

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

• A Klutch.sh account
• A GitHub account
• A GitHub OAuth application (created in GitHub Settings)
• A PostgreSQL database
• (Optional) A custom domain for your Octobox instance

Creating GitHub OAuth Application

Before deployment, create a GitHub OAuth app:

1. Go to GitHub Settings > Developer Settings > OAuth Apps
2. Click “New OAuth App”
3. Set Application name (e.g., “My Octobox”)
4. Set Homepage URL to your Octobox URL
5. Set Authorization callback URL to https://your-app.klutch.sh/auth/github/callback
6. Save the Client ID and Client Secret

Understanding Octobox Architecture

Octobox uses a straightforward Rails architecture:

Rails Application: Core application handling notifications and user interface.

PostgreSQL Database: Stores users, notifications, and settings.

Sidekiq Workers: Background jobs for syncing notifications.

Redis: Queue backend for background jobs and caching.

GitHub API: Fetches notifications via GitHub’s REST API.

Deploying Octobox on Klutch.sh

Create Your GitHub Repository

Create a new GitHub repository for your Octobox deployment configuration.

Create the Dockerfile

Create a Dockerfile in your repository root:

FROM ruby:3.1-slim

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

# Clone Octobox
WORKDIR /app
RUN git clone https://github.com/octobox/octobox.git .

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

# Precompile assets
RUN RAILS_ENV=production SECRET_KEY_BASE=dummy bundle exec rake assets:precompile

# Set environment
ENV RAILS_ENV=production
ENV RAILS_LOG_TO_STDOUT=true

EXPOSE 3000

CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

Configure the following environment variables:

Variable	Value
DATABASE_URL	postgresql://user:pass@host/octobox
GITHUB_CLIENT_ID	Your OAuth Client ID
GITHUB_CLIENT_SECRET	Your OAuth Client Secret
SECRET_KEY_BASE	Generate with rails secret
OCTOBOX_DATABASE_HOST	Database host
REDIS_URL	Redis connection URL

Attach Persistent Volumes

Add persistent storage:

Mount Path	Recommended Size	Purpose
/app/tmp	2 GB	Temporary files
/app/log	5 GB	Application logs

Deploy Background Worker

Create a separate app for Sidekiq:

FROM ruby:3.1-slim

# ... same setup as main app ...

CMD ["bundle", "exec", "sidekiq"]

Deploy Your Application

Click Deploy to start the build process.

Run Database Migrations

After deployment, run migrations:

1. Access the container
2. Run bundle exec rake db:migrate

Access Octobox

Navigate to https://your-app.klutch.sh and sign in with GitHub.

Using Octobox

Signing In

Connect your GitHub account:

1. Click “Sign in with GitHub”
2. Authorize the OAuth application
3. Grant notification access
4. Notifications sync automatically

Managing Notifications

Organize your inbox:

1. Star: Mark important notifications
2. Archive: Hide processed notifications
3. Mute: Silence specific threads
4. Snooze: Temporarily hide notifications

Filtering and Search

Find specific notifications:

• Filter by repository
• Filter by notification type (issue, PR, etc.)
• Filter by reason (mentioned, assigned, etc.)
• Full-text search

Keyboard Shortcuts

Navigate efficiently:

Shortcut	Action
j / k	Move down/up
o	Open notification
e	Archive
s	Star/unstar
m	Mute
?	Show all shortcuts

Auto-Archive Features

Reduce noise automatically:

• Archive merged pull requests
• Archive closed issues
• Archive when participating
• Configure in settings

Team Features

Multi-User Setup

Support multiple team members:

1. Each user signs in with their GitHub account
2. Each has their own notification inbox
3. Settings are per-user
4. Shared deployment, individual data

Organization Sync

Sync organization notifications:

1. Authorize organization access
2. Enable organization repos
3. Sync notifications across teams

Configuration Options

Notification Settings

Customize your experience:

1. Go to Settings
2. Configure sync frequency
3. Set auto-archive preferences
4. Configure email notifications

Personal Access Token

For private repositories:

1. Generate GitHub PAT
2. Add to your Octobox settings
3. Sync private repo notifications

Production Best Practices

Performance Optimization

• Run Sidekiq for background syncing
• Configure Redis for caching
• Optimize database queries
• Monitor sync jobs

Security Recommendations

• Secure OAuth credentials
• Use HTTPS exclusively
• Regular security updates
• Monitor API rate limits

Backup Strategy

1. Database Backups: Regular PostgreSQL dumps
2. Configuration: Document environment settings
3. OAuth: Store credentials securely

Troubleshooting Common Issues

Notifications Not Syncing

• Check GitHub API rate limits
• Verify OAuth token validity
• Review Sidekiq job status
• Check GitHub API status

Login Issues

• Verify OAuth callback URL
• Check Client ID/Secret
• Clear browser cookies
• Review OAuth scopes

Missing Notifications

• Ensure notification access granted
• Check repository visibility
• Verify organization authorization
• Review filter settings

Additional Resources

• Octobox Official Site
• Octobox GitHub Repository
• Octobox Wiki

Conclusion

Deploying Octobox on Klutch.sh provides a powerful way to manage GitHub notifications without drowning in noise. The inbox-style interface and smart filtering help developers stay on top of important updates while keeping the noise manageable. With persistent storage and always-on availability, you’ll never miss an important GitHub notification again.