DEV Community: Sulman Baig

Master Shopify Embedded Apps with Rails 8

Sulman Baig — Thu, 06 Feb 2025 06:00:00 +0000

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

✅ DO: Use App Bridge for Navigation

// 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 %>
<!DOCTYPE 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

✅ DO: Implement Proper Navigation

<%# 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

# Wrong
redirect_to settings_path

# Right
redirect_to settings_path(request.query_parameters)

Missing CSRF Protection

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!

Originally published at sulmanweb

Build Secure Shopify Apps with App Bridge

Sulman Baig — Mon, 03 Feb 2025 06:00:00 +0000

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 %>
<!DOCTYPE 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!

Originally published at sulmanweb.com

Rails CI/CD with Dokku & GitHub Actions

Sulman Baig — Thu, 30 Jan 2025 06:00:00 +0000

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

Rails 8 Production Setup with Dokku Guide

Sulman Baig ・ Jan 27

#ruby #rails #dokku
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!

Originally published at: https://sulmanweb.com.

Rails 8 Production Setup with Dokku Guide

Sulman Baig — Mon, 27 Jan 2025 06:00:00 +0000

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!

Originally published at https://sulmanweb.com.

Heroku to Dokku: A Rails Dev's Migration Tale

Sulman Baig — Thu, 23 Jan 2025 06:00:00 +0000

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!

Originally published at: https://sulmanweb.com

Rails 8 CI/CD: GitHub Actions & Kamal 2025

Sulman Baig — Mon, 20 Jan 2025 06:00:00 +0000

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

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

Sulman Baig ・ Jan 9

#rails #devops #docker #ruby

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://dev.to/sulmanweb/deploying-rails-8-applications-a-complete-guide-with-docker-kamal-and-cloudflare-3k)
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!

Originally published at: https://sulmanweb.com

Nice Gem will surely test it soon

Sulman Baig — Sat, 18 Jan 2025 17:49:19 +0000

Ruby on Rails - Calculating pricing based user's purchasing power parity

Waruna ・ Jan 10

#rails #ruby

Rails Self-Join Tables - Parent-Child Magic

Sulman Baig — Thu, 16 Jan 2025 06:00:00 +0000

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!

Originally published at https://sulmanweb.com.

Rails 8 CRUD: Modern Development Guide 2025

Sulman Baig — Mon, 13 Jan 2025 06:00:00 +0000

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

<!-- app/components/rich_text_editor_component.html.erb -->
<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.

Stay tuned for more articles on our Rails 8 journey. Feel free to reach out with questions or share your own importmap experiences!

Happy Coding!

Originally published at https://sulmanweb.com

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

Sulman Baig — Thu, 09 Jan 2025 06:00:00 +0000

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!

Originally published at sulmanweb.com

Rails GraphQL Auth - JWT, Email & Security

Sulman Baig — Mon, 06 Jan 2025 06:00:00 +0000

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!

Originally published at https://sulmanweb.com.

Rails Soft Delete & Audit Logging Guide

Sulman Baig — Thu, 02 Jan 2025 06:00:00 +0000

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!

Originally published at https://sulmanweb.com.

DEV Community: 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

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

Rails 8 Production Setup with Dokku Guide

Sulman Baig ・ Jan 27

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