Sulman Baig

Master Shopify Embedded Apps with Rails 8

Sulman Baig — Thu, 06 Feb 2025 05:00:39 GMT

Motivation

After building several Shopify embedded apps, I've learned valuable lessons about what works (and what definitely doesn't) in the embedded app environment. Today, I'm sharing these insights to help you avoid common pitfalls and build better Shopify apps.

The Challenge

Building embedded apps for Shopify presents unique challenges - particularly around navigation, authentication, and user experience. One of the biggest pitfalls? Trying to use regular URL navigation in an embedded app context.

Project Setup

First, let's look at the proper configuration for a Shopify embedded app:

# config/initializers/shopify_app.rb
ShopifyApp.configure do |config|
  config.embedded_app = true
  config.new_embedded_auth_strategy = false
  config.scope = "read_customers,write_customers"
  config.api_version = "2024-10"

  # Webhook configuration
  config.webhooks = [
    { topic: "app/uninstalled", address: "webhooks/app_uninstalled" },
    { topic: "customers/create", address: "webhooks/customers_create" }
  ]
end

Do's and Don'ts

// app/javascript/shopify_app.js
var AppBridge = window['app-bridge'];
var createApp = AppBridge.default;
window.app = createApp({
  apiKey: data.apiKey,
  host: data.host,
});

var actions = AppBridge.actions;
var TitleBar = actions.TitleBar;
TitleBar.create(app, {
  title: data.page,
});

❌ DON'T: Use Regular Rails Links

Avoid using regular Rails link_to helpers without proper App Bridge handling:

<%# Wrong way %>
<%= link_to "Settings", settings_path %>

<%# Right way %>
<%= link_to "Settings", settings_path(request.query_parameters) %>

✅ DO: Handle Authentication Properly

class AuthenticatedController < ApplicationController
  include ShopifyApp::EnsureHasSession

  before_action :verify_embedded_app_request

  private

  def verify_embedded_app_request
    if ShopifyAPI::Context.embedded? && 
       (!params[:embedded].present? || params[:embedded] != "1")
      redirect_to(ShopifyAPI::Auth.embedded_app_url(params[:host]).to_s + 
                 request.path, 
                 allow_other_host: true)
    end
  end
end

✅ DO: Implement Proper Flash Messages

# app/helpers/application_helper.rb
module ApplicationHelper
  def flash_class(type)
    case type.to_sym
    when :success, :notice
      "bg-green-50"
    when :error, :alert
      "bg-red-50"
    else
      "bg-blue-50"
    end
  end
end

✅ DO: Use Proper Layout for Embedded Apps

<%# app/views/layouts/embedded_app.html.erb %>
html>
<html lang="en">
  <head>
    <script src="https://unpkg.com/@shopify/app-bridge@3.7.9">script>
    <%= csrf_meta_tags %>
    <%= javascript_importmap_tags %>
  head>
  <body>
    <div id="app">
      <%= render 'shared/navbar' %>
      <%= yield %>
    div>

    <% if flash[:notice].present? || flash[:error].present? %>
      <script>
        document.addEventListener('DOMContentLoaded', function() {
          var Toast = window['app-bridge'].actions.Toast;

          <% if flash[:notice].present? %>
            Toast.create(window.app, {
              message: "<%= j flash[:notice] %>",
              duration: 5000
            }).dispatch(Toast.Action.SHOW);
          <% end %>
        });
      script>
    <% end %>
  body>
html>

❌ DON'T: Forget Query Parameters

When creating links or forms, always include the necessary query parameters:

# app/controllers/application_controller.rb
def maintain_query_parameters
  @query_parameters = request.query_parameters
end

<%# app/views/shared/_navbar.html.erb %>
<nav class="bg-white border-b border-gray-200 fixed w-full z-50">
  <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
    <div class="flex justify-between h-16">
      <div class="hidden md:flex md:items-center md:space-x-6">
        <%= link_to "Home", 
            root_path(params.except(:action, :controller).permit!.to_h), 
            class: "text-gray-600 hover:text-gray-900 px-3 py-2" %>
      div>
    div>
  div>
nav>

Common Pitfalls to Avoid

Direct URL Manipulation ```ruby
Wrong
redirect_to settings_path

Right

redirect_to settings_path(request.query_parameters)


2. **Missing CSRF Protection**
```ruby
class ApplicationController < ActionController::Base
  protect_from_forgery with: :exception
  skip_before_action :verify_authenticity_token, if: :valid_shopify_request?

  private

  def valid_shopify_request?
    return true if request.headers["HTTP_AUTHORIZATION"]&.start_with?("Bearer ")
    return true if params[:session].present?
    false
  end
end

Improper Session Handling

class Shop < ActiveRecord::Base
include ShopifyApp::ShopSessionStorageWithScopes

def api_version
 ShopifyApp.configuration.api_version
end
end

Best Practices for Success

Use App Bridge for All Navigation
Maintain Query Parameters
Implement Proper Error Handling
Use Appropriate Authentication Checks
Follow Shopify's Design Guidelines

Learning Journey

Building embedded Shopify apps has taught me the importance of proper navigation handling and session management. The biggest lesson? Never assume standard web development practices will work in an embedded context.

Results and Impact

Smoother user experience
Fewer authentication issues
Better app stability
Reduced support tickets

Next Steps

Enhanced Error Handling
- Implement better error boundaries
- Add detailed logging
Performance Optimization
- Optimize App Bridge usage
- Implement proper caching
User Experience Improvements
- Add loading states
- Enhance feedback mechanisms

Conclusion

Building embedded Shopify apps requires a different mindset from traditional web development. By following these best practices and avoiding common pitfalls, you can create robust, user-friendly applications that integrate seamlessly with the Shopify admin.

Have you encountered other challenges while building Shopify embedded apps? Share your experiences in the comments below!

Happy Coding!

Build Secure Shopify Apps with App Bridge

Sulman Baig — Mon, 03 Feb 2025 05:00:20 GMT

As a developer working with Shopify's ecosystem, I recently built a multi-tenant SaaS application that synchronizes customer data between Shopify stores and external services. In this article, I'll share my experience and technical insights into creating a secure, scalable Shopify app using App Bridge.

Project Overview

Our application needed to:

Handle multiple Shopify stores (multi-tenancy)
Process customer data securely
Provide a seamless embedded experience
Manage OAuth flows and webhooks
Handle billing subscriptions

Let's dive into how we accomplished these requirements using Rails 8 and Shopify's App Bridge.

Setting Up the Foundation

First, we set up our Rails application with the necessary Shopify integrations. Here's how our initial configuration looked:

ShopifyApp.configure do |config|
  config.embedded_app = true
  config.scope = "read_customers,write_customers"
  config.after_authenticate_job = false
  config.api_version = "2024-10"
  config.shop_session_repository = "Shop"
  config.webhooks = [
    { topic: "app/uninstalled", address: "webhooks/app_uninstalled" },
    { topic: "customers/create", address: "webhooks/customers_create" },
    { topic: "customers/update", address: "webhooks/customers_update" }
  ]
end

Multi-tenant Data Model

Our core data model revolves around the Shop model, which handles multi-tenancy:

class Shop < ActiveRecord::Base
  include ShopifyApp::ShopSessionStorageWithScopes

  has_many :customers, dependent: :destroy

  encrypts :api_key, deterministic: true
end

Embedded App Architecture

One of the key aspects was creating a seamless embedded experience. We achieved this through our layout configuration:

<%# app/views/layouts/embedded_app.html.erb %>
html>
<html lang="en">
  <head>
    <script src="https://unpkg.com/@shopify/app-bridge@3.7.9">script>
    <script>
      var AppBridge = window['app-bridge'];
      var createApp = AppBridge.default;
      var app = createApp({
        apiKey: "<%= ShopifyApp.configuration.api_key %>",
        host: "<%= @host %>",
        forceRedirect: true
      });
    script>
  head>
  <body>
    <%= yield %>
  body>
html>

Secure Authentication Flow

We implemented authenticated controllers to ensure secure access:

class AuthenticatedController < ApplicationController
  include ShopifyApp::EnsureHasSession

  before_action :ensure_store_settings

  private

  def ensure_store_settings
    redirect_to settings_path unless current_shop.setup_completed?
  end
end

Webhook Processing

Handling webhooks securely was crucial for our app. Here's our webhook processing implementation:

class WebhooksController < ApplicationController
  include ShopifyApp::WebhookVerification

  def customers_create
    shop = Shop.find_by(shopify_domain: params[:shop_domain])

    if shop
      shop.with_shopify_session do
        process_customer_data(params)
      end
    end

    head :ok
  end

  private

  def process_customer_data(data)
    CustomerProcessingJob.perform_later(
      shop_id: shop.id,
      customer_data: data
    )
  end
end

Background Job Processing

We used Solid Queue for reliable background processing:

class CustomerProcessingJob < ApplicationJob
  def perform(shop_id:, customer_data:)
    shop = Shop.find(shop_id)

    shop.with_shopify_session do
      customer = shop.customers.find_or_initialize_by(
        shopify_customer_id: customer_data["id"]
      )

      customer.update!(
        email: customer_data["email"],
        first_name: customer_data["first_name"],
        last_name: customer_data["last_name"]
      )
    end
  end
end

Billing Integration

We implemented Shopify's billing API to handle subscriptions:

config.billing = ShopifyApp::BillingConfiguration.new(
  charge_name: "App Subscription",
  amount: 4.99,
  interval: ShopifyApp::BillingConfiguration::INTERVAL_EVERY_30_DAYS,
  trial_days: 7
)

User Interface with Tailwind CSS

We created a clean, responsive interface using Tailwind CSS:

<div class="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8 pb-12 pt-20">
  <div class="sm:flex sm:items-center">
    <div class="sm:flex-auto">
      <h1 class="text-base font-semibold leading-6 text-gray-900">
        Customers
      h1>
      <p class="mt-2 text-sm text-gray-700">
        Manage your synchronized customers
      p>
    div>
  div>

  <%= render "customer_list", customers: @customers %>
div>

Lessons Learned

Throughout this project, I learned several valuable lessons:

Session Management: Always use Shopify's session tokens for authentication rather than storing raw access tokens.
Webhook Reliability: Implement idempotency in webhook processing to handle potential duplicate events.
Background Jobs: Use background jobs for any operations that might take more than a few seconds to complete.
Error Handling: Implement comprehensive error handling and logging, especially for webhook processing and API calls.
Security: Always encrypt sensitive data and never expose API keys in the frontend.

Conclusion

Building a multi-tenant Shopify app requires careful consideration of security, scalability, and user experience. By leveraging Rails, App Bridge, and modern development practices, we created a robust application that securely handles multiple stores and their data.

The combination of Shopify's App Bridge, Rails 8, and modern tools like Solid Queue and Tailwind CSS provided a solid foundation for building a scalable SaaS application.

Next Steps

If you're building a Shopify app, consider these recommendations:

Start with a solid authentication and authorization system
Implement webhook handling early in the development process
Use background jobs for long-running tasks
Plan for scalability from the beginning
Follow Shopify's security best practices

Remember that building a multi-tenant application requires careful consideration of data isolation and security at every level of your application.

Happy Coding!

Rails CI/CD with Dokku & GitHub Actions

Sulman Baig — Thu, 30 Jan 2025 05:00:23 GMT

As developers, we're always looking for ways to streamline our deployment process while maintaining security and reliability. Today, I'm excited to share my experience setting up an automated deployment pipeline for a Rails application using Dokku and GitHub Actions. This setup has transformed our deployment process from a manual, error-prone task into a smooth, automated workflow.

The Challenge

Managing production deployments can be tricky. You want something robust like Heroku but with more control over your infrastructure. Enter Dokku - a lightweight, open-source Platform as a Service (PaaS) that gives you Heroku-like features on your own server.

Prerequisites

Before we dive in, make sure you have:

A Dokku server set up and running

%[https://sulmanweb.com/rails-8-production-dokku-deployment-guide]
An existing Rails application deployed to the server
Administrative access to both the server and your GitHub repository

Setting Up Secure Deployment Keys

The first step in our automation journey is setting up secure SSH keys for deployment. This is crucial for allowing GitHub Actions to securely communicate with our Dokku server.

# On your production server
ssh-keygen -t ed25519 -f dokku

This command generates two files:

dokku - Your private key (keep this secret!)
dokku.pub - Your public key (safe to share)

Next, we need to configure Dokku and the server to trust these keys:

# Add the key to Dokku
echo "YOUR_PUBLIC_KEY_CONTENT" | dokku ssh-keys:add github

# Add to authorized keys for additional security
echo "YOUR_PUBLIC_KEY_CONTENT" >> ~/.ssh/authorized_keys

GitHub Repository Configuration

With our keys in place, we need to store the private key securely in GitHub. Here's how:

Navigate to your repository's Settings → Secrets and variables → Actions
Create a new secret named PRODUCTION_DOKKU_SSH_PRIVATE_KEY
Paste your private key content

This secret will be securely encrypted and only accessible during the deployment process.

The Magic: GitHub Actions Workflow

Now for the exciting part - setting up our automated deployment pipeline. Create or modify .github/workflows/ci.yml:

deploy_production:
    needs: [ test ]
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-24.04

    steps:
      - name: Cloning repo
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Push to dokku
        uses: dokku/github-action@master
        with:
          branch: 'main'
          trace: '1'
          git_push_flags: '--force'
          git_remote_url: 'ssh://dokku@SERVER_IP:22/APP_NAME_IN_DOKKU'
          ssh_private_key: ${{ secrets.PRODUCTION_DOKKU_SSH_PRIVATE_KEY }}

Let's break down what's happening here:

Workflow Triggers

if: github.event_name == 'push' && github.ref == 'refs/heads/main'

This condition ensures deployments only happen when code is pushed to the main branch - perfect for a trunk-based development workflow.

Job Dependencies

needs: [ test ]

By specifying needs: [ test ], we ensure our tests pass before any deployment occurs. This is crucial for maintaining code quality!

Deployment Configuration

The dokku/github-action@master action handles the heavy lifting:

branch: 'main' - Specifies which branch to deploy
trace: '1' - Enables detailed logging for troubleshooting
git_push_flags: '--force' - Ensures clean deployments
git_remote_url - Connects to your Dokku server
ssh_private_key - Securely authenticates using our previously configured key

The Deployment Process

With everything set up, deploying is as simple as:

git push origin main

This triggers the following sequence:

Your code is pushed to GitHub
GitHub Actions detects the push to main
The test suite runs
If tests pass, the deployment job begins
Your code is securely deployed to the Dokku server

Personal Insights and Tips

Through implementing this setup, I've learned some valuable lessons:

Security First: Always use dedicated deployment keys and never store sensitive information in your repository.
Test Dependencies: Make deployment dependent on test success to prevent broken code from reaching production.
Logging Matters: The trace: '1' option has saved hours of debugging by providing detailed deployment logs.

Looking Forward

This setup has dramatically improved our deployment workflow, but there's always room for enhancement. Future improvements might include:

Adding staging environment deployments
Implementing automatic database backups pre-deployment
Setting up deployment notifications in Slack

Remember, the goal of automation isn't just to save time - it's to build confidence in your deployment process and free up mental energy for solving more interesting problems.

Have you implemented a similar setup? I'd love to hear about your experiences and any improvements you've made to this workflow!

Happy deployments!

Rails 8 Production Setup with Dokku Guide

Sulman Baig — Mon, 27 Jan 2025 05:00:39 GMT

The Challenge: Modernizing Rails Deployment

When I recently needed to deploy my Rails 8 application with multiple databases, I faced a common dilemma: choosing between expensive managed solutions and complex self-managed servers. My requirements were specific:

Multiple PostgreSQL databases for different concerns
SSL certificate management
Automated deployment pipeline
Cost-effective hosting
Easy database management
Background job processing

Let me walk you through how I solved this using Dokku.

Setting Up Our Foundation

First, let's prepare our server. I chose a 2GB RAM VPS - here's why:

Dokku needs about 1GB RAM to operate smoothly
Rails 8 with Puma and background jobs needs the other 1GB
Anything less resulted in occasional memory issues during asset compilation

Initial Server Configuration

SSH into your server and install Dokku:

wget -NP . https://dokku.com/install/v0.35.13/bootstrap.sh
sudo DOKKU_TAG=v0.35.13 bash bootstrap.sh

After countless deployments, I've found this version to be particularly stable with Rails 8.

The Database Architecture

One of Rails 8's strengths is its multi-database support. In my setup, I separated concerns into four databases:

# Create our databases
dokku postgres:create rails_primary_db
dokku postgres:create rails_cache_db
dokku postgres:create rails_queue_db
dokku postgres:create rails_cable_db

Here's why I chose this architecture:

Primary DB: Core application data
Cache DB: Session and cache storage
Queue DB: Background job management
Cable DB: Action Cable subscriptions

The Magic of Database Linking

This is where things get interesting. When linking databases, Dokku generates unique environment variables:

# Link each database and capture the environment variable names
dokku postgres:link rails_primary_db your-rails-app
# Returns: DATABASE_URL=postgres://...

dokku postgres:link rails_cache_db your-rails-app
# Returns: DOKKU_POSTGRES_AQUA_URL=postgres://...

dokku postgres:link rails_queue_db your-rails-app
# Returns: DOKKU_POSTGRES_BLACK_URL=postgres://...

dokku postgres:link rails_cable_db your-rails-app
# Returns: DOKKU_POSTGRES_BLUE_URL=postgres://...

Rails 8 Configuration Magic

Here's how I configured my Rails 8 application to use these databases. In config/database.yml:

production:
  primary: &primary_production
    <<: *default
    database: <%= ENV['DATABASE_URL'] || 'rails_primary_db' %>
    url: <%= ENV['DATABASE_URL'] %>

  cache:
    <<: *primary_production
    database: <%= ENV['DOKKU_POSTGRES_AQUA_URL'] || 'rails_cache_db' %>
    migrations_paths: db/cache_migrate
    url: <%= ENV['DOKKU_POSTGRES_AQUA_URL'] %>

  queue:
    <<: *primary_production
    database: <%= ENV['DOKKU_POSTGRES_BLACK_URL'] || 'rails_queue_db' %>
    migrations_paths: db/queue_migrate
    url: <%= ENV['DOKKU_POSTGRES_BLACK_URL'] %>

  cable:
    <<: *primary_production
    database: <%= ENV['DOKKU_POSTGRES_BLUE_URL'] || 'rails_cable_db' %>
    migrations_paths: db/cable_migrate
    url: <%= ENV['DOKKU_POSTGRES_BLUE_URL'] %>

The Deployment Pipeline

Create a Procfile in your Rails root:

web: bin/rails server -p $PORT -e $RAILS_ENV
worker: bin/jobs
release: bundle exec rails db:migrate 2>/dev/null || bundle exec rails db:setup

I learned the hard way that the release command needs error handling for first deployments, hence the 2>/dev/null || bundle exec rails db:setup pattern.

Environment Configuration

Rails 8 needs specific environment variables. Here's my production setup:

# Rails essentials
dokku config:set your-rails-app RAILS_ENV=production
dokku config:set your-rails-app RACK_ENV=production
dokku config:set your-rails-app RAILS_MASTER_KEY=$(cat config/credentials/production.key)

# Rails 8 specifics
dokku config:set your-rails-app RAILS_SERVE_STATIC_FILES=true
dokku config:set your-rails-app RAILS_LOG_TO_STDOUT=true

Git Deployment Setup

Configure your local repository:

# Add Dokku remote
git remote add production dokku@your-server-ip:your-rails-app

# Verify remote addition
git remote show production

# Set deployment branch
dokku git:set your-rails-app deploy-branch main

SSL Configuration

Rails 8 expects HTTPS in production. Here's how to set it up with Let's Encrypt:

# Install the plugin
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

# Configure your domain
dokku domains:clear-global
dokku domains:set your-rails-app yourdomain.com

# Setup SSL
dokku letsencrypt:set your-rails-app email your@email.com
dokku letsencrypt:enable your-rails-app
dokku letsencrypt:cron-job --add

Deployment and Monitoring

Deploy your application:

git push production main

Monitor your deployment:

# Real-time logs
dokku logs your-rails-app -t

# Process status
dokku ps:report your-rails-app

# Database status
dokku postgres:info rails_primary_db

Troubleshooting Common Rails 8 Issues

During my deployments, I encountered several Rails 8-specific issues:

Asset Compilation Failures

 # Force a clean asset compilation
 dokku run your-rails-app bundle exec rails assets:clobber assets:precompile

Database Migration Issues

 # Run migrations manually if needed
 dokku run your-rails-app bundle exec rails db:migrate

Worker Process Management

 # Restart workers after config changes
 dokku ps:restart your-rails-app worker

Maintenance Tips

Based on my experience, here are some crucial maintenance practices:

Database Backups

# Backup all databases
for db in primary cache queue cable; do
  dokku postgres:export rails_${db}_db > ${db}_backup.dump
done

Performance Monitoring

Monitor your Rails 8 application's health:

# Check memory usage
dokku ps:report your-rails-app

# View error logs
dokku logs your-rails-app -t | grep ERROR

Conclusion

Deploying Rails 8 with Dokku has been a game-changer for my development workflow. The combination of Rails 8's robust multi-database support and Dokku's Heroku-like deployment experience has made managing production applications both cost-effective and developer-friendly.

Remember to:

Keep your Rails master key secure
Regularly backup all databases
Monitor worker processes
Keep an eye on memory usage

The setup might seem extensive, but once configured, deployments become as simple as git push production main. Feel free to reach out if you encounter any Rails 8-specific deployment challenges!

This guide reflects my real-world experience deploying Rails 8 applications with Dokku. As you work with this setup, you'll likely discover additional optimizations specific to your use case.

Happy deploying!

Heroku to Dokku: A Rails Dev's Migration Tale

Sulman Baig — Thu, 23 Jan 2025 05:00:44 GMT

The Cost-Benefit Realization

As a Rails developer who recently migrated from Heroku to Dokku, I want to share my journey and the surprising benefits I discovered. This transition wasn't just about cost savings—it opened up new possibilities for my deployment workflow.

The Heroku Challenge

Before diving into Dokku's benefits, let me share why I started looking for alternatives. Heroku had been my go-to platform for years, offering:

Zero-configuration deployments
Excellent developer experience
Reliable infrastructure
Built-in add-ons

However, recent changes created some challenges:

Removal of free tier
Significant cost increases for basic dynos
Sleep states affecting development apps
Add-on costs adding up quickly

Why Dokku Won Me Over

1. Cost Efficiency

# Monthly Cost Comparison for a Basic Rails Setup
heroku_cost = {
  basic_dyno: 7,
  postgres: 9,
  redis: 15,
  ssl: 20,
  total: 51
}

dokku_cost = {
  server_2gb: 10,
  managed_databases: 0,  # Included!
  ssl: 0,               # Free via Let's Encrypt
  total: 10
}

2. Infrastructure Control

Unlike Heroku's black box approach, Dokku lets me:

Choose my server provider (Digital Ocean, Linode, AWS)
Customize server resources
Configure nginx directly
Manage database backups my way

3. Multi-App Efficiency

One of my favorite discoveries:

# Deploy multiple apps on one server
dokku apps:create rails-app-1
dokku apps:create rails-app-2
dokku apps:create rails-app-3

# Each with its own domains and SSL
dokku domains:set rails-app-1 app1.domain.com
dokku domains:set rails-app-2 app2.domain.com

4. Familiar Workflow

Dokku maintains Heroku's git-based deployment:

# Just like Heroku
git push dokku main

# Even supports release phase
dokku config:set rails-app-1 DOKKU_RELEASE_COMMAND="rails db:migrate"

5. Database Flexibility

My Rails apps often need multiple databases:

# Create separate databases for different concerns
dokku postgres:create main_db
dokku postgres:create analytics_db
dokku postgres:create cache_db

# Link them easily
dokku postgres:link main_db rails-app

6. Custom Plugin Ecosystem

Beyond basic features:

# Install useful plugins
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
sudo dokku plugin:install https://github.com/dokku/dokku-redis.git

Real-World Benefits I've Experienced

Development Environment

Faster deployments (no queue waiting)
Direct log access
Quick database operations
Custom domain management

Production Advantages

Significant cost savings
Better resource utilization
Full control over backups
Custom monitoring solutions

Scaling Capabilities

# Scale processes individually
dokku ps:scale web=2
dokku ps:scale worker=1

# Monitor resource usage
dokku ps:report

Making the Transition Easier

Here's what helped me during migration:

Environment Variable Management

# Export from Heroku
heroku config -a your-app > config.txt

# Import to Dokku
while read line; do
  dokku config:set your-app $line
done < config.txt

Database Migration

# Export from Heroku
heroku pg:backups:capture
heroku pg:backups:download

# Import to Dokku
dokku postgres:import database < latest.dump

When to Choose Dokku Over Heroku

Consider Dokku when you:

Need cost-effective hosting
Want multiple apps on one server
Require custom infrastructure
Have basic sysadmin knowledge
Value deployment flexibility

Stay with Heroku if you:

Need enterprise-level support
Require zero server management
Want managed add-on services
Have a larger team needing access controls

Learning Curve and ROI

The initial setup took me about a day, but the benefits were immediate:

Monthly costs dropped by 80%
Deployment times improved
More control over infrastructure
Better understanding of my stack

Conclusion

My journey from Heroku to Dokku has been transformative. While Heroku remains an excellent platform, Dokku provides a powerful, cost-effective alternative that doesn't compromise on developer experience. The learning curve is worth the benefits, especially for Rails applications where cost and control matter.

Remember: Dokku isn't just a Heroku alternative—it's a different way of thinking about deployments that empowers developers to take control of their infrastructure while maintaining the simplicity we love about Platform as a Service solutions.

If you're considering the switch, feel free to reach out. The Rails community around Dokku is growing, and sharing experiences helps everyone succeed in their deployment journey!

Happy Coding!

Rails 8 CI/CD: GitHub Actions & Kamal 2025

Sulman Baig — Mon, 20 Jan 2025 05:00:26 GMT

In my previous article, we explored deploying Rails 8 applications using Docker and Kamal.

https://sulmanweb.com/deploy-rails-8-docker-kamal-production-guide

Today, I'm excited to share how we can take this deployment process to the next level by automating it with GitHub Actions. This automation will make our deployments more consistent, reduce human error, and save valuable development time.

Why Add GitHub Actions to Our Deployment Stack?

When I first started using Kamal for deployments, I found myself repeatedly running the same commands. While Kamal made the process straightforward, I knew we could make it even better. GitHub Actions provides the perfect solution by:

Automating deployments on code pushes to main
Ensuring consistent deployment environments
Managing secrets securely
Providing detailed deployment logs and history

Prerequisites

Before we dive in, make sure you have:

A Rails 8 application configured with Kamal (https://sulmanweb.com/deploy-rails-8-docker-kamal-production-guide)
A GitHub repository for your application
Access to your repository's settings to configure secrets

Setting Up GitHub Actions

Let's break down the process into manageable steps.

1. Creating the Workflow File

First, create a new file at .github/workflows/deploy.yml. This is where our deployment magic will happen.

name: Deploy to Production

on:
  push:
    branches:
      - main

permissions:
  contents: read
  packages: write
  id-token: write

jobs:
  deploy:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-24.04
    env:
      DOCKER_BUILDKIT: 1
      RAILS_ENV: production
      BUNDLE_WITHOUT: "development test"
      BUNDLE_WITH: tools

2. Setting Up Deployment Steps

Let's examine each step of our deployment process:

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: .ruby-version
          bundler-cache: true

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

These initial steps prepare our deployment environment:

checkout clones our repository
setup-ruby configures Ruby using our project's .ruby-version
setup-buildx enables Docker's advanced build capabilities

3. Configuring SSH Access

The SSH setup is crucial for secure server access:

      - name: Set up SSH
        run: |
          mkdir -p ~/.ssh
          echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          eval $(ssh-agent -s)
          ssh-add ~/.ssh/id_rsa
          ssh-keyscan xx.xx.xx.xx >> ~/.ssh/known_hosts
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

4. Running the Deployment

Finally, we execute Kamal:

      - name: Deploy with Kamal
        run: bin/kamal deploy
        env:
          RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
          KAMAL_REGISTRY_PASSWORD: ${{ secrets.KAMAL_REGISTRY_PASSWORD }}
          POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
          POSTGRES_PASS: ${{ secrets.POSTGRES_PASSWORD }}

Setting Up GitHub Secrets

Security is paramount in automated deployments. Here's how to set up your secrets in GitHub:

Navigate to your repository's Settings
Select "Secrets and variables" → "Actions"
Click "New repository secret"
Add the following secrets:
- SSH_PRIVATE_KEY: Your server's SSH private key
- RAILS_MASTER_KEY: Your Rails master key
- KAMAL_REGISTRY_PASSWORD: Docker registry password
- POSTGRES_PASSWORD: Database password

Pro tip: Generate strong passwords for these secrets using a password manager!

Understanding Environment Variables

Our workflow uses several environment variables:

DOCKER_BUILDKIT: 1: Enables Docker's modern build system
RAILS_ENV: production: Sets Rails environment
BUNDLE_WITHOUT: Optimizes gem installation
BUNDLE_WITH: tools: Ensures deployment tools are available

Deployment Flow

When you push to main, here's what happens:

GitHub Actions triggers the workflow
The environment is prepared with Ruby and Docker
SSH access is configured securely
Kamal executes the deployment
Your application is updated with zero downtime

Best Practices and Tips

Through my experience with this setup, I've learned some valuable lessons:

Test Your Workflow: Use GitHub Actions' "workflow_dispatch" trigger to test manually before automating.
Monitor Deployments: Watch your Actions tab for deployment logs.
Secure Your Secrets: Regularly rotate your credentials and use strong passwords.
Keep Dependencies Updated: Regularly update your GitHub Actions versions.

Troubleshooting Common Issues

If you encounter issues, check these common points:

SSH Connection Failures
- Verify your SSH private key format
- Ensure the server IP in known_hosts is correct
Docker Registry Issues
- Confirm your registry credentials
- Check Docker login status
Environment Variables
- Verify all secrets are properly set
- Check for typos in secret names

Conclusion

Automating deployments with GitHub Actions and Kamal has transformed our deployment process from a manual task to a streamlined, automated workflow. Not only does this save time, but it also provides consistency and reliability in our deployments.

Remember, automation is about finding the right balance between convenience and control. With this setup, we maintain full control over our deployment process while enjoying the benefits of automation.

What's your experience with automated deployments? I'd love to hear your thoughts and experiences in the comments below! 🚀

Happy Coding!

Rails Self-Join Tables: Parent-Child Magic

Sulman Baig — Thu, 16 Jan 2025 05:00:44 GMT

In modern web applications, we often need to represent hierarchical data structures where records can have parent-child relationships within the same table. Think of organizational charts, nested categories, or multi-level attributes. Today, I'll walk you through implementing self-referential associations in Ruby on Rails, using a practical example from a laboratory management system.

The Challenge

Recently, while building a laboratory information system, I needed to implement a flexible attribute system where each lab attribute could have multiple child attributes, creating a tree-like structure. For example, a "Blood Test" attribute might have child attributes like "Hemoglobin," "White Blood Cell Count," and "Platelet Count."

Technical Implementation

Let's break down the implementation into manageable steps and understand the underlying concepts.

Step 1: Database Migration

First, we need to set up our database structure. In Rails 8, we can generate a migration to add a self-referential foreign key:

# Terminal command
rails generate migration AddParentToLabAttribute parent:references

# db/migrate/YYYYMMDDHHMMSS_add_parent_to_lab_attribute.rb
class AddParentToLabAttribute < ActiveRecord::Migration[8.0]
  def change
    add_reference :lab_attributes, :parent, 
                  foreign_key: { to_table: :lab_attributes }
  end
end

This migration adds a parent_id column to our lab_attributes table, which will reference another record in the same table. The foreign_key option explicitly tells Rails that this reference points back to the same table.

Step 2: Model Definition

The magic happens in our model definition. Here's how we set up the self-referential association:

# app/models/lab_attribute.rb
class LabAttribute < ApplicationRecord
  # Parent association
  belongs_to :parent, 
             class_name: 'LabAttribute', 
             optional: true

  # Children association
  has_many :children, 
           class_name: 'LabAttribute',
           foreign_key: 'parent_id',
           dependent: :destroy,
           inverse_of: :parent

  # Validation to prevent circular references
  validate :prevent_circular_reference

  private

  def prevent_circular_reference
    if parent_id == id || 
       (parent.present? && parent.ancestor_ids.include?(id))
      errors.add(:parent_id, "cannot create circular reference")
    end
  end
end

Let's break down the key components:

belongs_to :parent - Establishes the relationship to the parent attribute
optional: true - Makes the parent association optional (root attributes don't have parents)
has_many :children - Sets up the inverse relationship
dependent: :destroy - Automatically deletes child attributes when the parent is deleted
inverse_of: :parent - Helps Rails optimize memory usage and maintain consistency

Step 3: Enhanced Functionality

Let's add some useful methods to work with our hierarchical structure:

# app/models/lab_attribute.rb
class LabAttribute < ApplicationRecord
  # Previous code...

  def root?
    parent_id.nil?
  end

  def leaf?
    children.empty?
  end

  def depth
    return 0 if root?
    1 + parent.depth
  end

  def ancestor_ids
    return [] if root?
    [parent_id] + parent.ancestor_ids
  end

  def ancestors
    LabAttribute.where(id: ancestor_ids)
  end

  def descendants
    children.flat_map { |child| [child] + child.descendants }
  end
end

Usage Examples

Here's how you can use this implementation in practice:

# Creating a hierarchy
blood_test = LabAttribute.create!(name: 'Blood Test')
hemoglobin = blood_test.children.create!(name: 'Hemoglobin')
wbc = blood_test.children.create!(name: 'White Blood Cell Count')

# Querying relationships
puts blood_test.children.pluck(:name)
# => ["Hemoglobin", "White Blood Cell Count"]

puts wbc.parent.name
# => "Blood Test"

puts hemoglobin.root?
# => false

puts blood_test.leaf?
# => false

puts wbc.depth
# => 1

Performance Considerations

When working with self-referential associations, keep these performance tips in mind:

Use eager loading to avoid N+1 queries:

LabAttribute.includes(:children, :parent).where(parent_id: nil)

Consider using counter caches for large hierarchies:

add_column :lab_attributes, :children_count, :integer, default: 0

For deep hierarchies, consider using closure tables or nested sets if you frequently need to query entire trees.

Conclusion

Self-referential table inheritance is a powerful pattern for modeling hierarchical data in Rails applications. While this implementation focuses on lab attributes, the same pattern can be applied to any domain requiring hierarchical data structures.

Remember to:

Validate against circular references
Consider the depth of your hierarchies
Use eager loading appropriately
Add indexes to foreign keys for better performance

Happy Coding!

Rails 8 CRUD: Modern Development Guide 2025

Sulman Baig — Mon, 13 Jan 2025 05:00:27 GMT

When our team decided to upgrade to Rails 8, we chose a more Rails-native approach using importmap for JavaScript management. This decision aligned perfectly with Rails' philosophy of convention over configuration, and I'm excited to share how this choice shaped our development experience.

Initial Setup and Modern Stack Choices

Let's start with setting up our Rails 8 project:

rails new modern_platform \
  --css tailwind \
  --database postgresql \
  --skip-test \
  --skip-system-test

Why no --javascript flag? Rails 8 comes with importmap by default, which I've found to be a game-changer for managing JavaScript dependencies. Here's how we configured our importmap:

# config/importmap.rb
pin "@hotwired/turbo-rails", to: "turbo.min.js"
pin "@hotwired/stimulus", to: "stimulus.min.js"
pin "@hotwired/stimulus-loading", to: "stimulus-loading.js"

# Third-party packages we're using
pin "chart.js", to: "https://ga.jspm.io/npm:chart.js@4.4.1/dist/chart.js"
pin "@rails/request.js", to: "https://ga.jspm.io/npm:@rails/request.js@0.0.9/src/index.js"
pin "trix"
pin "@rails/actiontext", to: "actiontext.js"

# Local JavaScript modules
pin_all_from "app/javascript/controllers", under: "controllers"
pin_all_from "app/javascript/components", under: "components"

Modern JavaScript Organization

One of the benefits of importmap is how naturally it fits with module-based JavaScript. Here's how we structure our JavaScript:

// app/javascript/controllers/post_form_controller.js
import { Controller } from "@hotwired/stimulus"
import { post } from "@rails/request.js"

export default class extends Controller {
  static targets = ["form", "preview"]
  static values = {
    previewUrl: String
  }

  async preview() {
    const formData = new FormData(this.formTarget)

    try {
      const response = await post(this.previewUrlValue, {
        body: formData
      })

      if (response.ok) {
        const html = await response.text
        this.previewTarget.innerHTML = html
      }
    } catch (error) {
      console.error("Preview failed:", error)
    }
  }
}

Component-Based Architecture

We've embraced ViewComponent with Stimulus, creating a powerful combination for reusable UI components:

# app/components/rich_text_editor_component.rb
class RichTextEditorComponent < ViewComponent::Base
  attr_reader :form, :field

  def initialize(form:, field:)
    @form = form
    @field = field
  end

  def stimulus_controller_options
    {
      data: {
        controller: "rich-text-editor",
        rich_text_editor_toolbar_value: toolbar_options.to_json
      }
    }
  end

  private

  def toolbar_options
    {
      items: [
        %w[bold italic underline strike],
        %w[heading-1 heading-2],
        %w[link code],
        %w[unordered-list ordered-list]
      ]
    }
  end
end


<div class="rich-text-editor" <%= stimulus_controller_options %>>
  <%= form.rich_text_area field,
    class: "prose max-w-none",
    data: { 
      rich_text_editor_target: "editor",
      action: "trix-change->rich-text-editor#onChange"
    } %>

  <div class="mt-2 text-sm text-gray-500" 
       data-rich-text-editor-target="counter">
    0 characters
  div>
div>

// app/javascript/controllers/rich_text_editor_controller.js
import { Controller } from "@hotwired/stimulus"
import Trix from "trix"

export default class extends Controller {
  static targets = ["editor", "counter"]
  static values = { 
    toolbar: Object,
    maxLength: Number 
  }

  connect() {
    this.setupToolbar()
    this.updateCounter()
  }

  onChange() {
    this.updateCounter()
  }

  updateCounter() {
    const text = this.editorTarget.value
    this.counterTarget.textContent = 
      `${text.length} characters`
  }

  setupToolbar() {
    if (!this.hasToolbarValue) return

    const toolbar = this.editorTarget
      .querySelector("trix-toolbar")

    // Customize toolbar based on configuration
    this.toolbarValue.items.forEach(group => {
      // Toolbar customization logic
    })
  }
}

Chart.js Integration with Importmap

Here's how we handle data visualization using Chart.js through importmap:

// app/javascript/controllers/analytics_chart_controller.js
import { Controller } from "@hotwired/stimulus"
import { Chart } from "chart.js"

export default class extends Controller {
  static values = {
    data: Object,
    options: Object
  }

  connect() {
    this.initializeChart()
  }

  initializeChart() {
    const ctx = this.element.getContext("2d")

    new Chart(ctx, {
      type: "line",
      data: this.dataValue,
      options: {
        ...this.defaultOptions,
        ...this.optionsValue
      }
    })
  }

  get defaultOptions() {
    return {
      responsive: true,
      maintainAspectRatio: false,
      plugins: {
        legend: {
          position: "bottom"
        }
      }
    }
  }
}

Performance Optimizations with HTTP/2

One advantage of importmap is its excellent performance with HTTP/2. Here's how we optimize our asset delivery:

# config/environments/production.rb
Rails.application.configure do
  # Use CDN for importmapped JavaScript
  config.action_controller.asset_host = ENV["ASSET_HOST"]

  # Enable HTTP/2 Early Hints
  config.action_dispatch.early_hints = true

  # Configure importmap hosts
  config.importmap.cache_sweepers << Rails.root.join("app/javascript")

  # Preload critical JavaScript
  config.action_view.preload_links_header = true
end

Testing JavaScript Components

We use Capybara with Cuprite for JavaScript testing:

# spec/system/posts_spec.rb
RSpec.describe "Posts", type: :system do
  before do
    driven_by(:cuprite)
  end

  it "previews post content", js: true do
    visit new_post_path

    find("[data-controller='post-form']").tap do |form|
      form.fill_in "Content", with: "**Bold text**"
      form.click_button "Preview"

      expect(form).to have_css(
        ".preview strong", 
        text: "Bold text"
      )
    end
  end
end

Deployment Considerations

Our production setup leverages HTTP/2 and CDN caching:

# nginx.conf
server {
  listen 443 ssl http2;

  # Enable asset caching
  location /assets/ {
    expires max;
    add_header Cache-Control public;
  }

  # Early hints for importmapped JavaScript
  location / {
    proxy_pass http://backend;
    http2_push_preload on;
  }
}

Parallel Query Execution: A Game-Changer

One of the most exciting features we discovered in Rails 8 was parallel query execution. During our performance optimization sprint, this became a crucial tool for handling complex dashboard pages:

# app/controllers/dashboards_controller.rb
class DashboardsController < ApplicationController
  def show
    # Execute multiple queries asynchronously
    posts_future = fetch_recent_posts.load_async
    comments_future = fetch_pending_comments.load_async
    analytics_future = ActiveRecord::Base.async_exec { fetch_analytics_data }
    notifications_future = fetch_user_notifications.load_async

    # Resolve the futures
    posts = posts_future.value
    comments = comments_future.value
    analytics = analytics_future.value
    notifications = notifications_future.value

    respond_to do |format|
      format.html do
        render locals: {
          posts: posts,
          comments: comments,
          analytics: analytics,
          notifications: notifications
        }
      end

      format.turbo_stream do
        render turbo_stream: [
          turbo_stream.update("dashboard-posts", partial: "posts/list", locals: { posts: posts }),
          turbo_stream.update("dashboard-analytics", partial: "analytics/summary", locals: { data: analytics })
        ]
      end
    end
  end

  private

  def fetch_recent_posts
    Post.visible_to(current_user)
        .includes(:author, :categories)
        .order(published_at: :desc)
        .limit(10)
  end

  def fetch_pending_comments
    Comment.pending_review
           .includes(:post, :author)
           .where(post: { author_id: current_user.id })
           .limit(15)
  end

  def fetch_analytics_data
    AnalyticsService.fetch_dashboard_metrics(
      user: current_user,
      range: 30.days.ago..Time.current
    )
  end

  def fetch_user_notifications
    current_user.notifications
               .unread
               .includes(:notifiable)
               .limit(5)
  end
end

To make this even more powerful, we integrated it with Stimulus for real-time updates:

// app/javascript/controllers/dashboard_controller.js
import { Controller } from "@hotwired/stimulus"
import { Chart } from "chart.js"

export default class extends Controller {
  static targets = ["analytics", "posts"]

  connect() {
    this.initializeCharts()
    this.startRefreshTimer()
  }

  disconnect() {
    if (this.refreshTimer) {
      clearInterval(this.refreshTimer)
    }
  }

  async refresh() {
    try {
      const response = await fetch(this.element.dataset.refreshUrl, {
        headers: {
          Accept: "text/vnd.turbo-stream.html"
        }
      })

      if (response.ok) {
        Turbo.renderStreamMessage(await response.text())
      }
    } catch (error) {
      console.error("Dashboard refresh failed:", error)
    }
  }

  startRefreshTimer() {
    this.refreshTimer = setInterval(() => {
      this.refresh()
    }, 30000) // Refresh every 30 seconds
  }

  initializeCharts() {
    if (!this.hasAnalyticsTarget) return

    const data = JSON.parse(this.analyticsTarget.dataset.metrics)
    this.createAnalyticsChart(data)
  }

  createAnalyticsChart(data) {
    const ctx = this.analyticsTarget.getContext("2d")

    new Chart(ctx, {
      type: "line",
      data: data,
      options: {
        responsive: true,
        maintainAspectRatio: false,
        animations: {
          tension: {
            duration: 1000,
            easing: 'linear'
          }
        }
      }
    })
  }
}

The combination of parallel queries and Turbo Streams gave us impressive performance improvements:

Dashboard load times dropped by 47%
Database connection usage became more efficient
Real-time updates felt smoother with optimistic UI updates

Learning Journey and Trade-offs

Moving to importmap wasn't without challenges. Here's what we learned:

Simplified Dependency Management: No more yarn/npm complexity
Better Caching: HTTP/2 multiplexing improved load times
Module Patterns: Encouraged cleaner JavaScript organization
Development Experience: Faster feedback loop without build steps

Looking Forward

Rails 8 with importmap has transformed our development workflow. The native integration with Hotwire and Stimulus, combined with HTTP/2 optimizations, has given us a modern, maintainable, and performant application stack.

Happy Coding!

Deploying Rails 8 Applications: A Complete Guide with Docker, Kamal, and Cloudflare

Sulman Baig — Thu, 09 Jan 2025 05:00:51 GMT

Introduction

When I first started deploying Rails applications, the process felt overwhelming. Today, I'm excited to share a complete guide that transforms this complexity into a straightforward process. Let's dive into deploying a Rails 8 app using Docker, with PostgreSQL containerization, all orchestrated by Kamal on a Hetzner server.

Prerequisites

Before we begin our deployment journey, you'll need:

A Rails 8 application ready for production
Docker installed locally
A Hetzner account
Domain name and Cloudflare account
1Password account (for secrets management)
Basic SSH knowledge

Step 1: Server and DNS Configuration

Hetzner Server Setup

Let's start by creating our production environment:

Create a Hetzner server with these specifications:

 - Ubuntu 24.04
 - ARM64 (Ampere) CPU
 - CAX11 size (or choose based on your needs)
 - IPv4 only configuration
 - Your SSH keys added

Cloudflare Configuration

Set up your domain with proper DNS and security settings:

DNS Configuration:

 - Add A record: @ → your-server-ip (Proxy enabled)
 - Add CNAME: www → @ (Proxy enabled)

SSL/TLS Settings:

 - Edge Certificates: Enable "Always use HTTPS"
 - Overview: Set SSL/TLS mode to "Full"

Page Rules for www to root redirect:

 URL: https://www.yourdomain.com/*
 Setting: Forwarding URL
 Status Code: 301 - Permanent Redirect
 Destination URL: https://yourdomain.com/$1

Step 2: Secrets Management

I've learned that proper secrets management is crucial. Let's set it up with 1Password:

Create a secure note in 1Password with these credentials:

 KAMAL_REGISTRY_PASSWORD: your-docker-registry-password
 RAILS_MASTER_KEY: your-rails-master-key
 POSTGRES_PASSWORD: your-postgres-password

Update .kamal/secrets to handle 1Password integration:

 SECRETS=$(kamal secrets fetch --adapter 1password --account YOUR_1PASSWORD_ACCOUNT_ID --from YOUR_VAULT_NAME/YOU_SECURE_NOTE KAMAL_REGISTRY_PASSWORD RAILS_PRODUCTION_KEY POSTGRES_PASSWORD)

 KAMAL_REGISTRY_PASSWORD=$(kamal secrets extract KAMAL_REGISTRY_PASSWORD $SECRETS)
 RAILS_MASTER_KEY=$(kamal secrets extract RAILS_PRODUCTION_KEY $SECRETS)
 POSTGRES_PASSWORD=$(kamal secrets extract POSTGRES_PASSWORD $SECRETS)

For more info visit Kamal Secrets.

Step 3: Database Configuration

PostgreSQL Setup

Create config/init.sql for database initialization:

 CREATE DATABASE IF NOT EXISTS `your_app_production`;
 CREATE DATABASE IF NOT EXISTS `your_app_production_cache`;
 CREATE DATABASE IF NOT EXISTS `your_app_production_queue`;
 CREATE DATABASE IF NOT EXISTS `your_app_production_cable`;

Configure PostgreSQL accessory in config/deploy.yml:

 accessories:
   postgres:
     image: postgres:16-alpine
     host: your-server-ip
     port: 5432
     options:
       restart: always
     env:
       clear:
         POSTGRES_USER: postgres
         POSTGRES_DB: your_app_production
       secret:
         - POSTGRES_PASSWORD
     files:
       - config/init.sql:/docker-entrypoint-initdb.d/init.sql
     volumes:
       - /var/lib/postgresql/your_app_production:/var/lib/postgresql/data

Update config/database.yml for production:

 production:
     primary: &primary_production
         <<: *default
         host: <%= ENV["DB_HOST"] %>
         database: your_app_production
         username: postgres
         password: <%= ENV["POSTGRES_PASSWORD"] %>
     cache:
         <<: *primary_production
         database: your_app_production_cache
         migrations_paths: db/cache_migrate
     queue:
         <<: *primary_production 
         database: your_app_production_queue
         migrations_paths: db/queue_migrate
     cable: 
         <<: *primary_production
         database: your_app_production_cable
         migrations_paths: db/cable_migrate

Step 4: Production Environment Configuration

Update config/environments/production.rb with these essential settings:

Rails.application.configure do
  # Asset handling
  config.require_master_key = false
  config.assets.css_compressor = nil
  config.assets.compile = false
  config.public_file_server.enabled = true
  config.asset_host = "https://yourdomain.com"
  config.assets.enabled = true
  config.assets.version = "1.0"

  # SSL and security
  config.ssl_options = { 
    redirect: { 
      exclude: ->(request) { request.path == "/up" } 
    } 
  }

  # Health checks
  config.silence_healthcheck_path = "/up"

  # Domain configuration
  config.hosts = [
    "yourdomain.com",
    /.*\.yourdomain\.com/
  ]

  config.host_authorization = { 
    exclude: ->(request) { request.path == "/up" } 
  }

  # URL options
  config.action_mailer.default_url_options = { 
    host: "yourdomain.com", 
    protocol: "https" 
  }

  routes.default_url_options = {
    host: "yourdomain.com",
    protocol: "https"
  }
end

Step 5: Kamal Deployment Setup

Kamal, Rails 8's built-in deployment tool, makes containerized deployment straightforward:

Update rest of config/deploy.yml:

service: your_app_name

registry:
  username: your_dockerhub_username
  password:
    - KAMAL_REGISTRY_PASSWORD

aliases:
    console: app exec --interactive --reuse "bin/rails console"
    shell: app exec --interactive --reuse "bash"
    logs: app logs -f
    dbc: app exec --interactive --reuse "bin/rails dbconsole"

image: your_dockerhub_username/your_app_name

builder:
    arch: arm64

proxy:
  ssl: true
  host: yourdomain.com

servers:
  web:
    hosts:
      - your_server_ip

volumes:
  - your_app_storage:/rails/storage:rw
  - /tmp/storage:/rails/tmp/storage:rw
  - your_app_data:/data

env:
  secret:
    - RAILS_MASTER_KEY
    - POSTGRES_PASSWORD
  clear:
    HOST: yourdomain.com
    RAILS_ENV: production
    DB_HOST: your_app-postgres
    SOLID_QUEUE_IN_PUMA: true
    RAILS_SERVE_STATIC_FILES: true
    RAILS_LOG_TO_STDOUT: true

Step 6: Deployment

Now for the exciting part - deploying our application:

Initial setup:
```
 bin/kamal setup
```
Watch the logs to ensure everything starts correctly:
```
 bin/kamal logs
```
For subsequent deployments:
```
 bin/kamal deploy
```

Deployment Verification Checklist

After deployment, I always verify these key points:

[ ] Health check endpoint (/up) responds
[ ] Database migrations completed successfully
[ ] Assets are serving correctly
[ ] SSL certificate is valid
[ ] www to root domain redirect works
[ ] PostgreSQL container is running and accessible

Troubleshooting Tips

From my experience, here are some common issues and solutions:

Database Connection Issues:
```
 bin/kamal dbc
```
Container Inspection:
```
 bin/kamal shell
```
PostgreSQL Logs:
```
 bin/kamal accessory logs postgres
```

For more info go to kamal-deploy.

Conclusion

Deploying a Rails 8 application might seem daunting at first, but with this structured approach, it becomes a manageable and repeatable process. I've learned that proper configuration of each component - from DNS to secrets management to database setup - is crucial for a robust production deployment.

Remember to always test your deployment in a staging environment first, and keep your secrets secure using proper management tools like 1Password.

Have you deployed a Rails application using this approach? I'd love to hear about your experience in the comments below! 🚀

Happy Coding!

Rails GraphQL Auth - JWT, Email & Security

Sulman Baig — Mon, 06 Jan 2025 05:00:15 GMT

Building a secure and scalable authentication system is crucial for modern web applications. Today, I'll share insights from implementing a robust GraphQL authentication system in Rails, with detailed explanations of each component.

🏗️ Architecture Overview

The authentication system consists of three main components:

JWT-based token authentication
Email verification workflow
Secure password management

Let's examine each component in detail.

🔑 JWT Authentication Implementation

Token Generation and Management

The core of our authentication relies on JWT tokens. Let's break down the key components:

class User < ApplicationRecord
  # Token generation for different purposes with specific lifetimes
  generates_token_for :auth_token, expires_in: 1.week
  generates_token_for :email_confirmation, expires_in: 8.hours
  generates_token_for :password_reset, expires_in: 1.hour
end

This code uses a custom token generation system where:

generates_token_for is a macro that sets up token generation for specific purposes
Each token type has its own expiration time
Tokens are bound to specific user data for verification

For example, when we call user.generate_token_for(:auth_token), it:

Creates a JWT token with user-specific claims
Sets an expiration time (1 week for auth tokens)
Signs the token with the application's secret key
Returns the encoded token for client use

Authentication Service

module Users
  class SignInService < ApplicationService
    def call
      return failure([USER_NOT_FOUND_MESSAGE]) unless user

      # Generate authentication token
      token = user.generate_token_for(:auth_token)

      # Log the authentication event
      log_event(user:, data: { username: user.username })

      # Return success response with token and user data
      success({ token:, user: })
    end

    private

    def user
      # Authenticate user using credentials
      @user ||= User.authenticate_by(permitted_params)
    end
  end
end

Key aspects of the service:

Validates user credentials
Generates an authentication token
Logs the authentication event
Returns a structured response

GraphQL Authentication Mutation

module Mutations
  class UserSignIn < BaseMutationWithErrors
    # Define required input arguments
    argument :password, String, required: true
    argument :username, String, required: true

    # Define return fields
    field :token, String, null: true
    field :user, Types::UserType, null: true

    def resolve(**args)
      result = Users::SignInService.call(args)
      {
        errors: result.errors,
        success: result.success?,
        token: result.success? ? result.data[:token] : nil,
        user: result.success? ? result.data[:user] : nil
      }
    end
  end
end

This mutation:

Accepts username and password
Calls the authentication service
Returns token and user data on success
Handles errors gracefully

📧 Email Verification System

Confirmation Service Implementation

module Users
  class SendConfirmationEmailService < ApplicationService
    def call
      return failure([USER_NOT_FOUND_ERROR]) unless user
      return failure([USER_ALREADY_CONFIRMED_ERROR]) if user.confirmed?

      send_confirmation_email
      log_event(user:, data: { confirmation_sent: true })
      success(CONFIRMATION_SENT_MSG)
    end

    private

    def send_confirmation_email
      # Generate confirmation email with secure token
      email = Email.create_confirmation_email!(user:)
      send_email(email)
    end
  end
end

The confirmation flow:

Checks user existence and confirmation status
Generates a secure confirmation token
Creates and sends confirmation email
Logs the confirmation attempt

Email Token Generation

class Email < ApplicationRecord
  def self.create_confirmation_email!(user:)
    token = user.generate_token_for(:email_confirmation)
    create!(
      to_emails: [user.email],
      template_id: Rails.application.credentials.dig(:sendgrid, :confirm_template_id),
      substitutions: [{ 
        "confirmation_url": "#{Settings.emails.confirm_url}?token=#{token}",
        name: user.name 
      }]
    )
  end
end

This creates a confirmation email with:

A secure, time-limited token
A personalized confirmation URL
User-specific template data

🔒 Security Implementation

Authentication Middleware

module Queries
  class BaseQuery < GraphQL::Schema::Resolver
    def authenticate_user!
      return if current_user

      raise GraphQL::ExecutionError.new(
        I18n.t('gql.errors.not_authenticated'),
        extensions: { code: 'AUTHENTICATION_ERROR' }
      )
    end

    def current_user
      context[:current_user] || Current.user
    end
  end
end

This middleware:

Verifies token presence and validity
Maintains user context throughout requests
Handles authentication errors consistently
Provides access to current user data

Password Security

class User < ApplicationRecord
  # Regular expression for password validation
  PASSWORD_FORMAT = /\A(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*(),.?":{}|<>])[A-Za-z\d!@#$%^&*(),.?":{}|<>]{8,72}\z/

  validates :password, 
    presence: true,
    length: { minimum: 8, maximum: 72 },
    format: { with: PASSWORD_FORMAT },
    if: :password_required?

  private

  def password_required?
    password_digest.nil? || password.present?
  end
end

Password requirements:

Minimum 8 characters
Maximum 72 characters (bcrypt limitation)
Must include lowercase and uppercase letters
Must include numbers and special characters
Validated only when necessary

🧪 Testing Strategy

RSpec.describe Users::SignInService do
  describe '#call' do
    context 'when credentials are valid' do
      it 'generates an authentication token' do
        result = service.call
        expect(result.data[:token]).to be_present
        expect(User.find_by_token_for(:auth_token, result.data[:token])).to eq(user)
      end

      it 'logs the authentication event' do
        expect { service.call }.to change(AuditLog, :count).by(1)
      end
    end

    context 'when credentials are invalid' do
      it 'returns appropriate error messages' do
        result = described_class.new(invalid_params).call
        expect(result.errors).to include(I18n.t('services.users.sign_in.user_not_found'))
      end
    end
  end
end

Our testing approach:

Verifies token generation and validation
Ensures proper error handling
Checks audit logging
Validates security constraints

Conclusion

By implementing these patterns, we've created a secure, maintainable authentication system that:

Provides secure token-based authentication
Handles email verification properly
Maintains high security standards
Scales well with application growth

The complete implementation demonstrates how these components work together in a production environment while maintaining security and user experience.

Happy Coding!

Rails Soft Delete & Audit Logging Guide

Sulman Baig — Thu, 02 Jan 2025 05:00:17 GMT

As financial applications grow in complexity, data integrity becomes paramount. Today, I'll share insights from implementing a robust soft deletion system with comprehensive audit logging in a Rails financial application. Let's explore how we can maintain data traceability while ensuring nothing is permanently lost.

The Challenge

In financial applications, simply deleting records isn't an option. We need to:

Track all changes to financial records
Maintain data relationships
Enable record restoration
Ensure audit compliance

Implementing Soft Delete with acts_as_paranoid

The acts_as_paranoid gem provides a solid foundation for soft deletion. Here's how we've implemented it in our Account model:

class Account < ApplicationRecord
  acts_as_paranoid

  belongs_to :currency, optional: true
  belongs_to :user
  has_many :transactions, dependent: :destroy

  validates :name, presence: true
  validates :balance, presence: true
end

We added a deleted_at timestamp column which, when set, effectively "hides" the record from normal queries while preserving it in the database.

Advanced Audit Logging System

We've built a comprehensive audit logging system that tracks every change to our financial records:

class AuditLog < ApplicationRecord
  acts_as_paranoid

  belongs_to :user, optional: true

  validates :class_name, presence: true
end

The audit logging is integrated into our service layer using a base service class:

class ApplicationService
  private

  def log_event(user:, data: {})
    event_data = { 
      user: user, 
      data: data, 
      class_name: self.class.to_s 
    }.compact
    AuditLog.create(event_data)
  end
end

Transaction Tracking Across Deletions

For financial transactions, we maintain a complete audit trail even after deletion. Here's how we handle transaction deletion:

class Transactions::DestroyService < ApplicationService
  def call
    return failure([TRANSACTION_NOT_FOUND_MESSAGE]) unless transaction
    return failure([USER_NOT_FOUND_MESSAGE]) unless user

    ActiveRecord::Base.transaction do
      transaction.destroy
      update_account_balance
      log_event(user: user, data: { transaction: transaction })
      success(TRANSACTION_DELETED_MESSAGE)
    rescue ActiveRecord::RecordInvalid => e
      failure(e.record.errors.full_messages)
    end
  end

  private

  def update_account_balance
    factor = transaction.transaction_type == 'expense' ? 1 : -1
    transaction.account.update!(
      balance: transaction.account.balance + (transaction.amount * factor)
    )
  end
end

Maintaining Data Integrity

To ensure data integrity, we've implemented several key features:

Atomic Transactions: All related operations are wrapped in database transactions:

ActiveRecord::Base.transaction do
transaction.destroy
update_account_balance
log_event(user: user, data: { transaction: transaction })
end

Relationship Preservation: We maintain relationships between records even after deletion:

class User < ApplicationRecord
acts_as_paranoid
has_many :audit_logs, dependent: :nullify
has_many :accounts, dependent: :destroy
has_many :transactions, dependent: :destroy
end

Automated Cleanup: We handle old soft-deleted records with a background job:

class RemoveSoftDeletedUsersJob < ApplicationJob
def perform
 return unless Settings.jobs.remove_soft_deleted_users.enabled

 User.deleted_before_time(eval(Settings.jobs.remove_soft_deleted_users.time).ago)
     .each(&:destroy_fully!)
end
end

Real-world Benefits

This implementation has provided several advantages:

Regulatory Compliance: Complete audit trails for financial transactions
Data Recovery: Easy restoration of accidentally deleted records
Performance: Minimal impact on database performance while maintaining data integrity
Maintenance: Automated cleanup of old soft-deleted records

Learning Outcomes

Building this system taught me several valuable lessons:

Always consider the broader implications of data deletion in financial systems
Design for auditability from the ground up
Balance between data retention and system performance
Importance of atomic operations in maintaining data consistency

Best Practices

When implementing a similar system, consider these recommendations:

Always use database transactions for related operations
Log both the action and the state of the data
Implement cleanup strategies for old soft-deleted records
Maintain relationships between related records even after deletion
Design the audit system to be queryable and maintainable

This implementation has proven robust in production, handling millions of financial transactions while maintaining complete traceability and data integrity. The combination of soft deletion and comprehensive audit logging provides the security and transparency essential for financial applications.

Remember, in financial applications, it's not just about storing data—it's about maintaining a verifiable history of every change while ensuring data integrity at every step.

Happy Coding!

Rails Testing for Financial Operations

Sulman Baig — Mon, 30 Dec 2024 05:00:20 GMT

Testing financial applications requires exceptional attention to detail and robust test coverage. In this article, we'll explore advanced testing patterns for financial operations using a real-world Rails application. We'll cover transaction testing, balance validations, and audit logging verification.

The Foundation: Service Objects and RSpec

Our financial application uses a service-object pattern to encapsulate business logic. Here's how we structure our tests:

RSpec.describe Transactions::CreateService do
  subject(:service) { described_class.new(params) }

  let(:user) { create(:user) }
  let(:account) { create(:account, balance: 100, user: user) }
  let(:params) do
    {
      user_id: user.id,
      account_id: account.id,
      amount: 50,
      transaction_type: 'expense'
    }
  end
end

Testing Financial Transactions

When testing financial transactions, we need to verify several aspects:

Balance updates
Transaction records
Audit logs
Error handling

Here's a comprehensive test example:

describe '#call' do
  context 'when creating an expense transaction' do
    it 'updates the account balance correctly' do
      result = service.call
      expect(result).to be_success
      expect(account.reload.balance).to eq(50) # 100 - 50
    end

    it 'creates an audit log' do
      expect { service.call }
        .to change(AuditLog, :count).by(1)
    end
  end

  context 'when creating an income transaction' do
    let(:params) do
      {
        user_id: user.id,
        account_id: account.id,
        amount: 50,
        transaction_type: 'income'
      }
    end

    it 'increases the account balance' do
      result = service.call
      expect(result).to be_success
      expect(account.reload.balance).to eq(150) # 100 + 50
    end
  end
end

Testing Money Transfers

Transfer operations are particularly critical as they involve multiple accounts. Here's how we test them:

RSpec.describe Transactions::TransferService do
  let(:user) { create(:user) }
  let(:account_from) { create(:account, user: user, balance: 1000) }
  let(:account_to) { create(:account, user: user, balance: 0) }
  let(:params) do
    {
      user_id: user.id,
      account_from_id: account_from.id,
      account_to_id: account_to.id,
      amount: 100
    }
  end

  describe '#call' do
    it 'transfers money between accounts' do
      service = described_class.new(params)
      result = service.call

      expect(result).to be_success
      expect(account_from.reload.balance).to eq(900)
      expect(account_to.reload.balance).to eq(100)
    end

    it 'creates two transactions' do
      expect { service.call }
        .to change(Transaction, :count).by(2)
    end
  end
end

Shared Examples for Common Behaviors

To maintain DRY tests, we use shared examples for common behaviors:

RSpec.shared_examples 'an audit log' do |service_call, should_create|
  if should_create
    it 'creates an audit log' do
      expect { instance_exec(&service_call) }
        .to change(AuditLog, :count).by(1)
    end
  else
    it 'does not create an audit log' do
      expect { instance_exec(&service_call) }
        .not_to change(AuditLog, :count)
    end
  end
end

# Usage in specs
describe 'successful transaction' do
  include_examples 'an audit log', 
    -> { service.call }, 
    true
end

Testing Edge Cases

Financial applications must handle edge cases gracefully:

describe 'edge cases' do
  context 'with insufficient funds' do
    let(:account) { create(:account, balance: 10) }
    let(:params) do
      {
        user_id: user.id,
        account_id: account.id,
        amount: 100,
        transaction_type: 'expense'
      }
    end

    it 'fails the transaction' do
      result = service.call
      expect(result).not_to be_success
      expect(account.reload.balance).to eq(10)
    end
  end

  context 'with invalid amounts' do
    let(:params) do
      {
        user_id: user.id,
        account_id: account.id,
        amount: -50,
        transaction_type: 'expense'
      }
    end

    it 'rejects negative amounts' do
      result = service.call
      expect(result).not_to be_success
    end
  end
end

Testing Currency Conversions

When dealing with multiple currencies, we need to test conversion accuracy:

RSpec.describe Currency do
  let(:usd) { create(:currency, code: 'USD', amount: 1.0) }
  let(:eur) { create(:currency, code: 'EUR', amount: 0.85) }

  describe 'currency conversion' do
    it 'converts amounts correctly' do
      account = create(:account, currency: eur, balance: 100)

      # Verify USD equivalent
      expect(account.balance_in_usd).to eq(117.65) # 100 / 0.85
    end
  end
end

Testing GraphQL Mutations

Our financial operations are exposed via GraphQL. Here's how we test them:

RSpec.describe Mutations::TransactionCreate do
  let(:user) { create(:user) }
  let(:account) { create(:account, user: user) }

  let(:query) do
    <<~GQL
      mutation($input: TransactionCreateInput!) {
        transactionCreate(input: $input) {
          success
          transaction { id amount }
        }
      }
    GQL
  end

  it 'creates a transaction through GraphQL' do
    variables = {
      input: {
        accountId: account.id,
        amount: 100,
        transactionType: 'EXPENSE'
      }
    }

    post '/graphql', params: { 
      query: query, 
      variables: variables.to_json 
    }, headers: auth_headers(user)

    expect(response.parsed_body['data']['transactionCreate'])
      .to include('success' => true)
  end
end

Best Practices and Recommendations

Always test in a transaction block to ensure database cleanliness
Use factory_bot for test data setup
Test both happy and unhappy paths
Verify audit logs for sensitive operations
Use decimal for money calculations to avoid floating-point errors
Test currency conversions with known exchange rates
Verify transaction atomicity in transfers
Test authorization and authentication

Conclusion

Testing financial operations requires a comprehensive approach that covers not just the happy path but also edge cases, error conditions, and audit requirements. By following these patterns and practices, you can build reliable financial applications with confidence in their correctness.

Remember that financial data is critical, and tests are your first line of defense against bugs and inconsistencies. Take the time to write thorough tests, and your future self (and your users) will thank you.

This testing approach has been battle-tested in production environments and provides a solid foundation for building robust financial applications. The key is to think about all possible scenarios and edge cases while maintaining clean, readable, and maintainable tests.

Happy Coding!

Building a GitHub Activity CLI - A Ruby Journey

Sulman Baig — Thu, 26 Dec 2024 05:00:17 GMT

Links

GitHub Repo → https://github.com/sulmanweb/github-activity-cli
Roadmap.sh Task → https://roadmap.sh/projects/github-user-activity
My Solution for UpVotes → https://roadmap.sh/projects/github-user-activity/solutions?u=67124acb791f57dd60b7e0e4

Have you ever wanted to quickly check someone's GitHub activity right from your terminal? I recently took on this challenge by building a simple yet powerful CLI tool in Ruby. Let me walk you through how I built this GitHub Activity CLI, sharing both the technical details and lessons learned along the way.

Project Overview

The GitHub Activity CLI is a command-line tool that fetches and displays a user's recent GitHub activities. It's built with Ruby and follows clean code principles while keeping the implementation straightforward and maintainable.

The Challenge

The project requirements came from roadmap.sh's GitHub User Activity project. The main goals were to:

Fetch a user's recent GitHub activities using the GitHub API
Display the activities in a readable format
Handle various types of GitHub events (pushes, issues, PRs, etc.)
Implement proper error handling

Project Structure

I organized the code into a clean, modular structure:

├── bin
│   └── github-activity    # Executable CLI script
└── lib
    ├── activity_formatter.rb   # Formats different event types
    ├── github_activity.rb      # Main application logic
    └── github_client.rb        # Handles GitHub API communication

Technical Implementation

1. The GitHub Client

The heart of the application is the GitHubClient class that handles all API communications:

class GitHubClient
  BASE_URL = 'https://api.github.com'

  def fetch_user_events(username)
    uri = URI("#{BASE_URL}/users/#{username}/events")
    response = make_request(uri)

    case response
    when Net::HTTPSuccess
      JSON.parse(response.body)
    when Net::HTTPNotFound
      raise "User '#{username}' not found"
    else
      raise "Failed to fetch GitHub activity: #{response.message}"
    end
  end
end

I used Ruby's built-in Net::HTTP library to keep dependencies minimal. The client handles basic error cases and returns parsed JSON data.

2. Event Formatting

One of the interesting challenges was formatting different types of GitHub events. I created a dedicated ActivityFormatter class that handles this using a clean pattern:

class ActivityFormatter
  def format(event)
    case event['type']
    when 'PushEvent'
      format_push_event(event)
    when 'CreateEvent'
      format_create_event(event)
    when 'IssuesEvent'
      format_issues_event(event)
    # ... other event types
    end
  end
end

This approach makes it easy to add support for new event types and keeps the formatting logic organized.

3. The Main Application

The GitHubActivity class ties everything together:

class GitHubActivity
  def initialize(username)
    @username = username
    @client = GitHubClient.new
    @formatter = ActivityFormatter.new
  end

  def run
    events = @client.fetch_user_events(@username)
    if events.empty?
      puts "No recent activity found for user '#{@username}'"
      return
    end

    display_events(events)
  end
end

User Experience

I focused on making the CLI intuitive and user-friendly. Users can simply run:

./bin/github-activity username

The output is clean and readable:

Recent GitHub activity for sulmanweb:
--------------------------------------------------
Pushed 2 commits to sulmanweb/project
Created branch in sulmanweb/new-repo
Closed issue 'Bug fix needed' in sulmanweb/app

Learning Outcomes

Building this CLI taught me several valuable lessons:

API Integration: Working with the GitHub API showed me the importance of good error handling and response parsing.
Code Organization: Breaking the functionality into separate classes made the code more maintainable and testable.
User Experience: Even for a CLI tool, user experience matters. Clear output and helpful error messages make a big difference.

Supporting the Project

Want to help make the GitHub Activity CLI even better? There are several ways you can contribute:

Financial Support

⭐ Star the repository to show your support
💝 Consider upvoting my solution at GitHub Activity CLI solution page
🎁 Share the project with your network

Technical Contributions

🐛 Report bugs and suggest features through GitHub Issues
🔧 Submit pull requests for bug fixes or enhancements
📚 Help improve the documentation
🌐 Help with translations if you speak multiple languages

Future Improvements

While the current version works well, there's always room for improvement:

Add authentication to handle API rate limits
Include more detailed event information
Add filtering options for specific event types
Implement caching for faster repeated queries

Getting Started

Want to try it out? Here's how:

Clone the repository
Make the CLI executable: chmod +x bin/github-activity
Run it: ./bin/github-activity

Conclusion

Building this GitHub Activity CLI was a great exercise in creating a focused, useful tool while maintaining clean code practices. It shows how a relatively simple idea can be turned into a practical utility that others can use and build upon.

The source code is available on GitHub, and I welcome any feedback or contributions from the community. Happy coding! 🚀

Task Tracker CLI

Sulman Baig — Mon, 23 Dec 2024 05:00:06 GMT

Links

RubyGems.org → https://rubygems.org/gems/task_tracker_cli
GitHub Repo → https://github.com/sulmanweb/task_tracker_cli
Roadmap.sh Task → https://roadmap.sh/projects/task-tracker
My Solution for UpVotes → https://roadmap.sh/projects/task-tracker/solutions?u=67124acb791f57dd60b7e0e4

As part of my ongoing journey to improve my skills as a developer, I decided to work on a portfolio project that could challenge me while solving a practical problem. The project requirements were shared on roadmap.sh, and it immediately struck me as an ideal opportunity to create something versatile—a command-line tool for tracking tasks. Naturally, I chose Ruby for its simplicity and flexibility, and what began as a simple idea soon led me to publish my first Ruby gem!

The Idea: A Command-Line Task Tracker

The project I picked from roadmap.sh was a task-tracking tool that could easily record, update, and delete tasks from the command line. I have always loved command-line utilities—there's something empowering about typing commands and getting instant feedback. So, I wanted to build a tool that not only met the project requirements but also provided a clean and seamless experience for command-line enthusiasts like myself.

Creating the Gem: `task_tracker_cli`

After some initial tinkering, I realized I wanted this task tracker to be more accessible and easy to use, not only for myself but for anyone who might find it useful. That's when I decided to go the extra mile and turn the tool into a Ruby gem: task_tracker_cli.

The result? A simple installation process with gem install task_tracker_cli, and you're ready to start organizing your tasks right from the terminal!

Example Usage

Here is an example of how to use the tool:

# Install the gem and everything is ready to go
gem install task_tracker_cli

# Adding a new task
task-cli add "Buy groceries"
# Output: Task added successfully (ID: 1)

# Updating and deleting tasks
task-cli update 1 "Buy groceries and cook dinner"
task-cli delete 1

# Marking a task as in progress or done
task-cli mark-in-progress 1
task-cli mark-done 1

# Listing all tasks
task-cli list

# Listing tasks by status
task-cli list done
task-cli list todo
task-cli list in-progress

# Uninstall the gem
gem uninstall task_tracker_cli

You can also find more usage examples in the README of the repository and on roadmap.sh.

Why Turn It into a Gem?

Creating a gem was not originally part of the plan, but as I kept working, I realized that this was a perfect opportunity to package my work in a way that others could easily use, contribute to, and learn from. Gems are essentially Ruby's way of packaging libraries or tools, which means anyone can install it, use it, or even tweak it to their needs. By publishing it, I also learned the whole process of how to create, build, and publish a gem—skills that will undoubtedly be useful in my future development work.

Want to Try It?

If you're interested in giving this tool a try, you can find the gem on RubyGems.org, and the source code is available on GitHub. Feel free to explore, fork, or even contribute to the project! Also, don't forget to star the repo 🙏

Supporting the Project

This project was created as part of a community challenge on roadmap.sh. I'd greatly appreciate your support! You can check out my solution and upvote it on the task tracker solution page 🙏. Your upvotes would mean a lot to me and encourage me to create even more helpful projects.

If you're on your own learning journey, I highly recommend joining roadmap.sh and checking out some of the projects there. It's a great way to level up your skills, share your work, and get feedback from an engaged community of learners and developers.

Conclusion

Creating this task tracker CLI tool was an incredibly enriching experience for me. I not only got to dive deep into Ruby and explore gem creation, but I also created a tool that could genuinely help others stay organized and productive. I hope you'll find it useful, and I'd love to hear any feedback or suggestions you may have.

Happy coding, and keep building awesome stuff!

Build a Currency Exchange Service in Ruby on Rails

Sulman Baig — Thu, 19 Dec 2024 05:00:50 GMT

Working with exchange rates in Rails applications can be tricky. After implementing currency handling in several production apps, I've developed a robust pattern that I'll share with you today. We'll build a service that fetches live exchange rates from Currency Layer API and integrates smoothly with Rails.

🎯 What We'll Cover:

Setting up a reusable currency exchange service
Implementing background rate updates
Handling API integration gracefully
Testing our implementation

Project Setup

First, let's add the necessary gems to our Gemfile:

gem 'httparty'  # For API requests
gem 'solid_queue'  # For background jobs

Building the Currency Exchange Service

I prefer using Plain Old Ruby Objects (POROs) for API integrations. Here's why - they're easy to test, maintain, and modify. Let's build our service:

# app/services/currency_exchange.rb
class CurrencyExchange
  include HTTParty
  base_uri 'https://api.currencylayer.com'

  def initialize
    @options = { 
      query: { 
        access_key: Rails.application.credentials.currency_layer.api_key 
      } 
    }
  end

  def self.list
    new.list
  end

  def self.live
    new.live
  end
end

Pro Tip 💡 I'm using class methods (self.list and self.live) as convenience wrappers around instance methods. This gives us flexibility - we can instantiate the class directly when we need to customize behavior, or use the class methods for quick access.

Handling API Responses

Let's build clean value objects for our data:

class CurrencyExchange
  # ...

  GlobalCurrency = Struct.new(:code, :name)
  Conversion = Struct.new(:from, :to, :rate)

  def list
    res = self.class.get('/list', @options)
    return res.parsed_response['currencies'].map { |code, name| 
      GlobalCurrency.new(code, name) 
    } if res.success?
    []
  end

  def live
    res = self.class.get('/live', @options)
    return [] unless res.success?

    res.parsed_response['quotes'].map do |code, rate|
      Conversion.new(code[0..2], code[3..], rate.to_f.round(4))
    end
  end
end

Why This Approach Works 🎯

Value objects provide a clean interface
Empty arrays as fallbacks prevent nil checking
Response parsing is encapsulated
Rate rounding handles floating-point precision

Database Integration

We need to store our currency data. Here's our migration:

class CreateCurrencies < ActiveRecord::Migration[7.2]
  def change
    create_table :currencies do |t|
      t.string :code, null: false
      t.decimal :amount, precision: 14, scale: 4, default: 1.0
      t.string :name, null: false
      t.datetime :converted_at
      t.datetime :deleted_at

      t.timestamps
    end

    add_index :currencies, :code, unique: true
    add_index :currencies, :name
    add_index :currencies, :deleted_at
  end
end

Model Implementation

class Currency < ApplicationRecord
  acts_as_paranoid  # Soft deletes

  has_many :accounts, dependent: :nullify

  validates :name, presence: true
  validates :code, presence: true, uniqueness: true
  validates :amount, presence: true, 
            numericality: { greater_than_or_equal_to: 0.0 }
end

Automated Rate Updates

Here's where it gets interesting. We'll use a background job to update rates:

class UpdateCurrencyRatesJob < ApplicationJob
  def perform
    Currencies::UpdateRatesService.call
  end
end

The actual update service:

module Currencies
  class UpdateRatesService < ApplicationService
    def call
      CurrencyExchange.live.each do |conversion|
        update_rate(conversion)
      end
    end

    private

    def update_rate(conversion)
      Currency.find_by(code: conversion.to)&.update(
        amount: conversion.rate,
        converted_at: Time.current
      )
    end
  end
end

Scheduling Updates

Configure your scheduler in config/recurring.yml:

staging:
  update_currency_rates:
    class: UpdateCurrencyRatesJob
    queue: background
    schedule: '0 1 */2 * *'  # Every 2 days at 1 AM

Testing Strategy

Here's how I test this setup:

RSpec.describe CurrencyExchange do
  describe '.list' do
    it 'returns structured currency data' do
      VCR.use_cassette('currency_layer_list') do # https://github.com/vcr/vcr
        currencies = described_class.list
        expect(currencies).to all(be_a(described_class::GlobalCurrency))
      end
    end

    it 'handles API failures gracefully' do
      allow(described_class).to receive(:get).and_return(
        double(success?: false)
      )
      expect(described_class.list).to eq([])
    end
  end
end

Model Tests

RSpec.describe Currency do
  describe 'validations' do
    it 'requires a valid exchange rate' do
      currency = build(:currency, amount: -1)
      expect(currency).not_to be_valid
    end

    it 'enforces unique currency codes' do
      create(:currency, code: 'USD')
      duplicate = build(:currency, code: 'USD')
      expect(duplicate).not_to be_valid
    end
  end
end

Usage in Your Application

Here's how you'd use this in your app:

# Fetch available currencies
currencies = CurrencyExchange.list
puts "Available currencies: #{currencies.map(&:code).join(', ')}"

# Get current rates
rates = CurrencyExchange.live
rates.each do |conversion|
  puts "1 #{conversion.from} = #{conversion.rate} #{conversion.to}"
end

Common Pitfalls to Avoid ⚠️

Don't store sensitive API keys in your codebase. Use Rails credentials:
```
EDITOR="code --wait" bin/rails credentials:edit
```
Don't update rates synchronously during user requests. Always use background jobs.
Don't forget to handle API rate limits. Currency Layer has different limits for different plans.

Production Considerations 🚀

Error Monitoring: Add Sentry or similar error tracking:
```
Sentry.capture_exception(e) if defined?(Sentry)
```

Rate Limiting: Implement exponential backoff for API failures:

def with_retry
retries ||= 0
yield
rescue StandardError => e
retry if (retries += 1) < 3
raise e
end

Logging: Add structured logging for debugging:

Rails.logger.info(
event: 'currency_rate_update',
currency: conversion.to,
rate: conversion.rate
)

Remember: Currency exchange rates are critical financial data. Always validate your implementation thoroughly and consider using paid API tiers for production use.

Service Objects: Level Up Your Rails Architecture

Sulman Baig — Mon, 16 Dec 2024 05:00:07 GMT

Introduction

In modern Rails applications, organizing business logic effectively is crucial for maintainability and scalability. One powerful pattern that has emerged is the use of Service Objects - Plain Old Ruby Objects (POROs) that encapsulate specific business operations. In this article, we'll explore how Service Objects can be implemented for handling GraphQL mutations and background jobs, using real-world examples from a financial transaction management system.

Why Service Objects?

Traditional Rails applications often struggle with "fat" models and controllers that violate the Single Responsibility Principle. Service Objects help solve this by:

Encapsulating complex business logic
Improving testability
Enhancing code reusability
Providing clearer application architecture

Basic Structure of a Service Object

Let's look at the base Service Object pattern implemented in our application:

class ApplicationService
  attr_reader :params

  def self.call(params = {})
    new(params).call
  end

  def initialize(params = {})
    @params = params.is_a?(String) ? JSON.parse(params, symbolize_names: true) : params
  end

  def call
    raise NotImplementedError, "#{self.class} must implement #call"
  end

  private

  def transaction(&)
    ActiveRecord::Base.transaction(&)
  end

  def log_event(user:, data: {})
    event_data = { user:, data:, class_name: self.class.to_s }.compact
    AuditLog.create(event_data)
  end

  Result = Struct.new(:success, :data, :errors, keyword_init: true) do
    alias_method :success?, :success
  end

  def success(data = {})
    Result.new(success: true, data:, errors: nil)
  end

  def failure(errors)
    Result.new(success: false, data: nil, errors:)
  end
end

Real-World Example: Transaction Management

Let's examine how Service Objects handle complex business logic in a financial transaction system:

module Transactions
  class CreateService < ApplicationService
    def call
      validate_dependencies ||
        create_transaction
    end

    private

    def validate_dependencies
      return failure([USER_NOT_FOUND_MESSAGE]) unless user
      return failure([ACCOUNT_NOT_FOUND_MESSAGE]) unless account
      return failure([CATEGORY_NOT_FOUND_MESSAGE]) unless category || permitted_params[:transfer] == true

      false
    end

    def create_transaction
      ActiveRecord::Base.transaction do
        transaction = Transaction.new(permitted_params)
        transaction.transaction_time = Time.current if transaction.transaction_time.blank?
        transaction.save!

        multiplier = transaction.transaction_type == 'expense' ? -1 : 1
        account.update!(balance: account.balance + (transaction.amount * multiplier))

        log_event(user:, data: { transaction: })
        success(transaction)
      rescue ActiveRecord::RecordInvalid => e
        failure(e.record.errors.full_messages)
      end
    end
  end
end

Benefits in Practice

1. Clear Interface

Service Objects provide a consistent interface through the call method:

result = Transactions::CreateService.call(
  user_id: current_user.id,
  account_id: params[:account_id],
  amount: 100.00,
  transaction_type: 'expense'
)

if result.success?
  # Handle success
else
  # Handle failure
end

2. Integrated Error Handling

The Result object pattern provides a clean way to handle success and failure states:

def failure(errors)
  Result.new(success: false, data: nil, errors:)
end

def success(data = {})
  Result.new(success: true, data:, errors: nil)
end

3. Transaction Safety

Services can easily wrap operations in database transactions:

def transfer_money
  ActiveRecord::Base.transaction do
    CreateService.call(user_id: user.id, account_id: account_to.id,
                       transaction_type: 'income', transfer: true, **permitted_params)
    CreateService.call(user_id: user.id, account_id: account_from.id,
                       transaction_type: 'expense', transfer: true, **permitted_params)
    success(TRANSACTION_CREATED_MESSAGE)
  end
end

4. Audit Trail Integration

Built-in logging capabilities for tracking business operations:

def log_event(user:, data: {})
  event_data = { user:, data:, class_name: self.class.to_s }.compact
  AuditLog.create(event_data)
end

Integration with GraphQL Mutations

Service Objects integrate seamlessly with GraphQL mutations:

module Mutations
  class TransactionCreate < BaseMutationWithErrors
    def resolve(**args)
      auth_result = authenticate_user!
      return auth_result unless auth_result[:success]

      result = Transactions::CreateService.call(user_id: current_user.id, **args)
      {
        errors: result.errors,
        success: result.success?,
        transaction: result.success? ? result.data : nil
      }
    end
  end
end

Testing Service Objects

Service Objects are highly testable, as demonstrated by our RSpec examples:

RSpec.describe Transactions::CreateService do
  subject(:service) { described_class.new(params) }

  let(:user) { create(:user) }
  let(:account) { create(:account, balance: 100, user:) }
  let(:params) do
    {
      user_id: user.id,
      account_id: account.id,
      amount: 100,
      transaction_type: 'expense'
    }
  end

  describe '#call' do
    context 'when valid' do
      it 'creates the transaction and updates balance' do
        result = service.call
        expect(result).to be_success
        expect(account.reload.balance).to eq(0)
      end
    end
  end
end

Best Practices for Service Objects

Single Responsibility: Each service should do one thing well
Immutable Input: Use initialized parameters instead of instance variables
Result Objects: Always return a consistent result object
Transaction Safety: Wrap related operations in transactions
Audit Trail: Log important business events
Validation: Handle all edge cases and validation upfront
Testing: Write comprehensive tests for each service

Conclusion

Service Objects provide a powerful way to organize business logic in Rails applications. They offer clear benefits in terms of code organization, maintainability, and testability. When implemented consistently, they create a predictable pattern for handling complex business operations, whether in GraphQL mutations, background jobs, or other application components.

Remember that Service Objects are not a silver bullet - they should be used judiciously where they add value to your application architecture. For simple CRUD operations, traditional Rails patterns might still be the better choice.

The key is to identify complex business operations that benefit from encapsulation and isolation, and implement Service Objects for those specific cases. This approach leads to more maintainable and testable code while keeping the rest of your application simple and Rails-like.

Happy Coding!

Setting Up GraphQL and GraphiQL in Rails: A Comprehensive Guide

Sulman Baig — Thu, 12 Dec 2024 05:00:21 GMT

GraphQL is becoming increasingly popular as an alternative to REST APIs, offering more flexibility and efficiency in data fetching. In this guide, we'll walk through setting up GraphQL and GraphiQL in a Rails application, using practical examples from a real-world implementation.

Prerequisites

Ruby on Rails 7.2+
Ruby 3.3+
Basic understanding of Rails applications

Step 1: Adding Required Gems

First, add the necessary gems to your Gemfile:

gem 'graphql', '2.3.14'
gem 'graphiql-rails', '1.10.1'

Step 2: Installing GraphQL

Run the following commands to install GraphQL and generate the base files:

bundle install
rails generate graphql:install

This will create the basic GraphQL structure in your Rails application:

app/
└── graphql/
    ├── types/
    │   ├── base_object.rb
    │   ├── base_enum.rb
    │   ├── base_input_object.rb
    │   ├── base_interface.rb
    │   ├── base_scalar.rb
    │   ├── base_union.rb
    │   ├── query_type.rb
    │   └── mutation_type.rb
    ├── mutations/
    │   └── base_mutation.rb
    └── [your_app]_schema.rb

Step 3: Setting Up GraphQL Controller

Create a GraphQL controller to handle requests:

class GraphqlController < ApplicationController
  def execute
    variables = prepare_variables(params[:variables])
    query = params[:query]
    operation_name = params[:operationName]
    context = {
      current_user: current_user  # This comes from ApplicationController
    }
    result = YourAppSchema.execute(query,
                                 variables: variables,
                                 context: context,
                                 operation_name: operation_name)
    render json: result
  rescue StandardError => e
    raise e unless Rails.env.development?
    handle_error_in_development(e)
  end

  private
  # ... [rest of the controller code]
end

Authentication Setup

The current_user method is defined in your ApplicationController. Here's how to set it up:

class ApplicationController < ActionController::API
  def auth_header
    request.headers['Authorization']&.split&.last
  end

  def current_user
    Current.user = User.find_by_token_for(:auth_token, auth_header)
    @current_user ||= Current.user
  end
end

This setup allows you to:

Extract the authentication token from the request headers
Find the corresponding user
Make the user available throughout your GraphQL resolvers via context

You can then access the current user in any resolver or mutation:

module Mutations
  class BaseMutation < GraphQL::Schema::RelayClassicMutation
    def current_user
      context[:current_user]
    end

    def authenticate_user!
      raise GraphQL::ExecutionError, 'Not authenticated' unless current_user
    end
  end
end

Step 4: Configuring GraphiQL

Add GraphiQL configuration in config/initializers/graphiql.rb:

GraphiQL::Rails.config.header_editor_enabled = true
GraphiQL::Rails.config.title = 'Your API Name'

Update your config/application.rb to handle cookies for GraphiQL:

config.middleware.use ActionDispatch::Cookies
config.middleware.use ActionDispatch::Session::CookieStore
config.middleware.insert_after(ActionDispatch::Cookies, ActionDispatch::Session::CookieStore)

Step 5: Setting Up Routes

Add GraphQL routes to config/routes.rb:

Rails.application.routes.draw do
  post "/graphql", to: "graphql#execute"

  if !Rails.env.production?
    mount GraphiQL::Rails::Engine, at: "/graphiql", graphql_path: "/graphql"
  end
end

Step 6: CORS Configuration

If you're building an API, configure CORS in config/initializers/cors.rb:

Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins "*"
    resource "*",
      headers: :any,
      methods: [:get, :post, :put, :patch, :delete, :options, :head]
  end
end

Best Practices

1. Structured Type Definitions

Organize your types in a modular way:

module Types
  class BaseObject < GraphQL::Schema::Object
    edge_type_class(Types::BaseEdge)
    connection_type_class(Types::BaseConnection)
    field_class Types::BaseField
  end
end

2. Implement Base Mutations

Create a base mutation class for common functionality:

module Mutations
  class BaseMutation < GraphQL::Schema::RelayClassicMutation
    argument_class Types::BaseArgument
    field_class Types::BaseField
    input_object_class Types::BaseInputObject
    object_class Types::BaseObject
  end
end

3. Error Handling

Implement consistent error handling across your GraphQL API:

module Mutations
  class BaseMutationWithErrors < BaseMutation
    field :errors, [String], null: true
    field :success, Boolean, null: false

    def handle_errors(record)
      {
        success: false,
        errors: record.errors.full_messages
      }
    end
  end
end

Testing Your Setup

After completing the setup, you can access GraphiQL at http://localhost:3000/graphiql in development. Try this query:

query {
  __schema {
    types {
      name
    }
  }
}

Security Considerations

Limit GraphiQL to non-production environments
Implement proper authentication
Use query depth limiting to prevent complex nested queries
Consider implementing rate limiting

Conclusion

With this setup, you have a solid foundation for building a GraphQL API in Rails. The included GraphiQL interface provides a powerful tool for testing and documenting your API during development.

Remember to:

Keep your schema well-organized
Implement proper error handling
Follow security best practices
Write comprehensive tests for your GraphQL endpoints

This setup provides a robust starting point for building scalable GraphQL APIs with Rails.

Happy Coding!

Transform Your Codebase into Comprehensive Documentation with Markdown

Sulman Baig — Mon, 09 Dec 2024 05:00:45 GMT

Introduction

Welcome to the age of AI. The world is moving at lightning speed towards artificial intelligence, and programmers have an array of built-in tools in code editors like Zed, VSCode, and Cursor. These editors have the capability to analyze large codebases and assist in resolving issues or creating features.

I've tested many of these editors, but sometimes even including the codebase in chat doesn't provide the full picture, which means the results often fall short or lack the quality the repository requires. The worst-case scenario arises when an AI chat starts producing circular problems: solving one problem introduces a new issue, and fixing that issue reintroduces the first problem.

The core challenge here is the limited access to the whole codebase due to constraints on the number of files or file sizes that AI tools can process.

Moreover, let’s talk about direct AI models like Claude, Perplexity, and ChatGPT. Since their inception, these tools have come a long way. Now, ChatGPT allows attachment of files in chat, but it still doesn't support submitting zipped folders or entire repositories, meaning it cannot consider your whole code. The same limitation exists for Claude and Perplexity. It would be incredibly beneficial if we could give these AI tools our code in a compressed form—something that isn’t spread across hundreds of files and is readable by the AI.

Solution: A Ruby Script to Convert a Codebase into Markdown

Why Ruby?

The first question that comes to mind is: why Ruby?

Simply put, I like and work in Ruby. There is no ulterior or mind-boggling reason.

What Does This Ruby Script Do?

You provide the root folder path of your codebase to the script, and it will create Markdown files, each with a maximum size of 100KB. These files will contain code blocks with the content of each file, alongside a project structure tree. Files and folders listed in your .gitignore or specified in the script will be excluded.

Why Markdown and 100KB Files?

Markdown: Markdown is a lightweight markup language that works well for documentation. It’s text-based, making it easy to read and compatible with most personal knowledge management tools like Notion or Obsidian.
File Size Limitation: Some AI tools, especially Claude, do not read files larger than 100KB. Therefore, the script enforces this limit. You can adjust the limit by changing the script parameters.

The Ruby Script: `ruby_to_md.rb`

Below is the Ruby script that converts your codebase into Markdown files:

https://gist.github.com/sulmanweb/ee1541b1739b06db6695370cbc8a480d

require 'fileutils'
require 'digest'
ALWAYS_IGNORE = ['.git', 'tmp', 'log', '.ruby-lsp', '.github', '.devcontainer', 'storage', '.annotaterb.yml', 'public', '.cursorrules'].freeze
IGNORED_EXTENSIONS = %w[.jpg .jpeg .png .gif .bmp .svg .webp .ico .pdf .tiff .raw .keep .gitkeep .sample .staging].freeze
MAX_FILE_SIZE = 1_000_000 # 1MB
CHUNK_SIZE = 100_000 # 100KB
def read_gitignore(directory_path)
  gitignore_path = File.join(directory_path, '.gitignore')
  return [] unless File.exist?(gitignore_path)
  File.readlines(gitignore_path).map(&:chomp).reject(&:empty?)
end
def ignored?(path, base_path, ignore_patterns)
  relative_path = path.sub("#{base_path}/", '')
  return true if ALWAYS_IGNORE.any? { |dir| relative_path.start_with?(dir + '/') || relative_path == dir }
  return true if IGNORED_EXTENSIONS.include?(File.extname(path).downcase) || File.basename(path) == '.keep'
  ignore_patterns.any? do |pattern|
    File.fnmatch?(pattern, relative_path, File::FNM_PATHNAME | File::FNM_DOTMATCH) ||
      File.fnmatch?(File.join('**', pattern), relative_path, File::FNM_PATHNAME | File::FNM_DOTMATCH)
  end
end
def convert_to_markdown(file_path)
  extension = File.extname(file_path).downcase[1..]
  format = extension.nil? || extension.empty? ? 'text' : extension
  begin
    content = File.read(file_path, encoding: 'UTF-8')
    "## #{File.basename(file_path)}\n\n```#{format}\n#{content.strip}\n```\n\n"
  rescue StandardError => e
    "## #{File.basename(file_path)}\n\n[File content not displayed: #{e.message}]\n\n"
  end
end
def generate_tree_markdown(tree, prefix = '')
  result = ''
  tree.each do |key, value|
    result += "#{prefix}- #{key}\n"
    result += generate_tree_markdown(value, prefix + '  ') if value.is_a?(Hash)
  end
  result
end
def write_chunked_output(output_file, content)
  base_name = File.basename(output_file, '.*')
  extension = File.extname(output_file)
  dir_name = File.dirname(output_file)
  chunk_index = 1
  offset = 0
  while offset < content.length
    chunk = content[offset, CHUNK_SIZE]
    chunk_file = File.join(dir_name, "#{base_name}_part#{chunk_index}#{extension}")
    File.open(chunk_file, 'w:UTF-8') do |file|
      file.write("---\n")
      file.write("chunk: #{chunk_index}\n")
      file.write("total_chunks: #{(content.length.to_f / CHUNK_SIZE).ceil}\n")
      file.write("---\n\n")
      file.write(chunk)
    end
    puts "Markdown file created: #{chunk_file}"
    offset += CHUNK_SIZE
    chunk_index += 1
  end
end
def process_directory(directory_path, output_file)
  ignore_patterns = read_gitignore(directory_path)
  markdown_content = "---\nencoding: utf-8\n---\n\n# Project Structure\n\n"
  file_contents = []
  file_tree = {}
  Dir.glob("#{directory_path}/**/*", File::FNM_DOTMATCH).each do |file_path|
    next if File.directory?(file_path)
    next if ['.', '..'].include?(File.basename(file_path))
    next if ignored?(file_path, directory_path, ignore_patterns)
    next if File.size(file_path) > MAX_FILE_SIZE
    relative_path = file_path.sub("#{directory_path}/", '')
    parts = relative_path.split('/')
    current = file_tree
    parts.each_with_index do |part, index|
      if index == parts.size - 1
        current[part] = nil
      else
        current[part] ||= {}
        current = current[part]
      end
    end
    file_contents << convert_to_markdown(file_path)
  end
  markdown_content += generate_tree_markdown(file_tree)
  markdown_content += "\n# File Contents\n\n"
  markdown_content += file_contents.join("\n")
  write_chunked_output(output_file, markdown_content)
end
if ARGV.length != 2
  puts "Usage: ruby script.rb  "
  exit 1
end
input_directory = ARGV[0]
output_file = ARGV[1]
process_directory(input_directory, output_file)

Script Usage

The script requires two arguments:

Path to Codebase: The root directory of your project.
Output File Name: The base name for the generated Markdown files.

You can run the script, for example, as follows:

ruby ruby_to_md.rb ~/st/gradwinner gradwinner.md

This will create files like:

gradwinner_part1.md
gradwinner_part2.md
gradwinner_part3.md and so on.

Note: Files and folders listed in .gitignore will be ignored in the resultant documentation files.

Key Script Features

ALWAYS_IGNORE: This constant lists folders and files that need to be ignored in addition to those specified in .gitignore.
IGNORED_EXTENSIONS: This constant lists the file extensions (e.g., images) that should not be included in the documentation.
CHUNK_SIZE: You can modify this constant to increase or decrease the amount of data in each Markdown file.
MAX_FILE_SIZE: Files larger than this size will be ignored to prevent overwhelming the documentation.

Note: Many chat tools have a limit of 25 files that can be uploaded at once, so you may need to adjust the script according to your requirements.

Conclusion

This Ruby script helps you convert a code repository into documentation in Markdown format, providing a structured overview and content breakdown. It’s an ideal solution when working with AI tools that have file size or file number limitations, making your codebase more accessible to them in a condensed and readable form.

If you have feedback or improvements to suggest, feel free to contribute!

Happy Coding!

Implementing Multi-Select Enums in Ruby on Rails with PostgreSQL

Sulman Baig — Mon, 02 Dec 2024 05:00:43 GMT

In our previous article (linked below), we explored how to implement single-select enums in a Ruby on Rails application. In this post, we will extend that discussion to include the implementation of multi-select enums using arrays in Ruby on Rails with PostgreSQL.

https://sulmanweb.com/postgresql-enum-types-rails-7-guide

Introduction to Multi-Select Enums

Enums are a convenient way to handle a set of predefined values in your application. Sometimes, however, you might need to associate multiple values with a single record. For example, an article might belong to several categories such as "blog," "snippet," or "vlog." In this case, using an array of enums is a suitable solution that provides the flexibility to assign multiple categories.

Why Use Enum Arrays?

PostgreSQL enum arrays offer several advantages:

Better performance compared to string arrays due to internal optimizations.
Type safety at the database level, reducing the chance of invalid data being saved.
Reduced storage space compared to text arrays, making your database more efficient.
Improved query performance with GIN (Generalized Inverted Index) indexing, which is particularly useful for fast lookups on array columns.

Setting Up the Migration

Let's implement a multi-category system for an Article model. First, generate the migration:

rails g migration AddCategoriesToArticles categories:enum

Modify the generated migration to define an enum type and add the new column:

class AddCategoriesToArticles < ActiveRecord::Migration[7.2]
  def change
    create_enum :categories_enum, %w[
      blog
      snippet
      vlog
    ]
    add_column :articles, :categories, :enum, enum_type: :categories_enum, array: true, default: []
    add_index :articles, :categories, using: 'gin'
  end
end

In the migration above, the array: true option enables multiple values to be stored in the categories column. For optimal performance with array columns, PostgreSQL recommends using a GIN index to speed up querying.

Apply the migration:

rails db:migrate

Model Configuration

Next, define the enum in your Article model with proper validations and methods:

class Article < ApplicationRecord
  validates :categories, array_inclusion: { in: %w[blog snippet vlog] }

  # Remove duplicates before saving
  def categories=(types)
    super(types.uniq)
  end

  # Convenience method for checking category presence
  def has_category?(category)
    categories.include?(category)
  end
end

In this model, the array_inclusion validation ensures that only the specified strings are included in the categories array. The custom setter method categories= removes duplicate values before saving them to the database, ensuring data integrity.

Usage Examples

Here are some examples of how you can work with multi-select enums in Rails:

# Create an article with multiple categories
article = Article.create(categories: ['blog', 'vlog'])

# Add a category
article.categories << 'snippet'
article.save

# Query articles with a specific category
articles_with_blog = Article.where("'blog' = ANY(categories)")

The array_inclusion validation ensures that only permitted values are stored, while the custom setter prevents duplicate categories. For optimal query performance when filtering by categories, PostgreSQL will utilize the GIN index automatically.

Conclusion

PostgreSQL enum arrays in Rails provide a robust solution for handling multi-select fields with better performance and data integrity compared to string arrays. This pattern is particularly valuable for content management systems, tagging systems, or any scenario that requires multiple categorizations. By combining the use of enum arrays and proper indexing, you can ensure that your application remains performant as the data grows.

Happy Coding!

Leveraging PostgreSQL 16 Enum Types in Rails 7+: A Step-by-Step Guide

Sulman Baig — Mon, 25 Nov 2024 05:00:29 GMT

If you're a Rails developer, you've probably heard about the recent improvements in Rails 8, including optimizations for SQLite. While I mainly use PostgreSQL for my projects, these updates have piqued my curiosity, and I'm always interested in exploring what's new.

In this article, I'll guide you through leveraging PostgreSQL 16 enums in Rails 7+, showing you how to add an enum column to an article model, allowing you to define specific categories like blog, snippet, and vlog. Enums offer better data integrity and readability, making your code more maintainable.

Adding an Enum Column to Your Rails Model

To add a category enum column to the articles table, start by generating a migration:

rails g migration AddCategoryToArticles category:string

Next, modify the generated migration as follows to create an enum type and assign it to the column:

class AddCategoryToArticles < ActiveRecord::Migration[7.2]
  def change
    create_enum :categories, %w[
      blog
      snippet
      vlog
    ]
    add_column :articles, :category, :enum, enum_type: :categories
    add_index :articles, :category
  end
end

Run the migration:

rails db:migrate

This will create an enum type called categories in PostgreSQL and add a corresponding enum column to the articles table. You can verify the change in the schema file, where you'll see both the enum definition and the updated column.

Defining Enum in Your Model

Now, let's add the enum definition in the Article model:

class Article < ApplicationRecord
  enum :category, {
    blog: "blog",
    snippet: "snippet",
    vlog: "vlog",
  }, validate: true

  validates :category, presence: true
end

The validate: true option ensures that the enum is validated automatically with inclusion checks. If the category field is required, make sure to backfill existing articles before adding validates :category, presence: true.

Adding a Scope for Filtering by Category

To easily filter articles by their category, you can add a scope to your model:

scope :by_category, ->(category) { where(category: category) }

This scope allows you to perform queries like Article.by_category("blog") to filter articles by a specific category.

Conclusion

Using PostgreSQL enums in Rails provides type safety and keeps your database schema organized. This approach is particularly useful for fields with a fixed set of values, like categories in a blog or types in a content management system.

Happy Coding!

Sulman Baig

Master Shopify Embedded Apps with Rails 8

Motivation

The Challenge

Project Setup

Do's and Don'ts

✅ DO: Use App Bridge for Navigation

❌ DON'T: Use Regular Rails Links

✅ DO: Handle Authentication Properly

✅ DO: Implement Proper Flash Messages

✅ DO: Use Proper Layout for Embedded Apps

❌ DON'T: Forget Query Parameters

✅ DO: Implement Proper Navigation

Common Pitfalls to Avoid

Wrong

Right

Best Practices for Success

Learning Journey

Results and Impact

Next Steps

Conclusion

Build Secure Shopify Apps with App Bridge

Project Overview

Setting Up the Foundation

Multi-tenant Data Model

Embedded App Architecture

Secure Authentication Flow

Webhook Processing

Background Job Processing

Billing Integration

User Interface with Tailwind CSS

Lessons Learned

Conclusion

Next Steps

Rails CI/CD with Dokku & GitHub Actions

The Challenge

Prerequisites

Setting Up Secure Deployment Keys

GitHub Repository Configuration

The Magic: GitHub Actions Workflow

Workflow Triggers

Job Dependencies

Deployment Configuration

The Deployment Process

Personal Insights and Tips

Looking Forward

Rails 8 Production Setup with Dokku Guide

The Challenge: Modernizing Rails Deployment

Setting Up Our Foundation

Initial Server Configuration

The Database Architecture

The Magic of Database Linking

Rails 8 Configuration Magic

The Deployment Pipeline

Environment Configuration

Git Deployment Setup

SSL Configuration

Deployment and Monitoring

Troubleshooting Common Rails 8 Issues

Maintenance Tips

Database Backups

Performance Monitoring

Conclusion

Heroku to Dokku: A Rails Dev's Migration Tale

The Cost-Benefit Realization

The Heroku Challenge

Why Dokku Won Me Over

1. Cost Efficiency

2. Infrastructure Control

3. Multi-App Efficiency

4. Familiar Workflow

5. Database Flexibility

6. Custom Plugin Ecosystem

Real-World Benefits I've Experienced

Development Environment

Production Advantages

Scaling Capabilities

Making the Transition Easier

When to Choose Dokku Over Heroku

Learning Curve and ROI