Forem: Lakshay Tyagi

Connecting a Biometric Fingerprint Device to a Rails Web App Using Python — A Complete Walkthrough

Lakshay Tyagi — Thu, 07 May 2026 09:40:42 +0000

👋 Introduction

When I was building a gym management system for a real gym in New Delhi, one of the most interesting challenges was connecting a physical biometric fingerprint device to my cloud-hosted Ruby on Rails app.

The gym wanted to:

✅ Track member attendance via fingerprint scanning
✅ Automatically deny access to members with expired subscriptions
✅ Prevent duplicate check-ins
✅ See attendance on the admin dashboard in real-time

The catch? The biometric device only speaks to the local network. My Rails app is hosted on Render (cloud). They can't talk to each other directly.

The solution? A Python bridge script running on the gym's laptop that reads fingerprint punches from the device and forwards them to the Rails API via HTTP.

This post covers the entire pipeline — Python bridge → Rails API → Database — with real code from production.

🏗️ Architecture: The Full Pipeline

┌─────────────────────┐
│  ZK Fingerprint      │
│  Biometric Device    │
│  (192.168.1.201)     │
└──────────┬──────────┘
           │ pyzk SDK (TCP)
           ▼
┌──────────────────────────┐
│  Python Bridge Script    │
│  (bridge.py)             │
│  Runs on gym laptop      │
│  Polls every 20 seconds  │
│  Deduplicates locally    │
└──────────┬───────────────┘
           │ HTTP POST (JSON)
           ▼
┌──────────────────────────────────────┐
│  Ruby on Rails API (Render cloud)    │
│  POST /api/biometric_attendances     │
│                                      │
│  1. Find biometric mapping           │
│  2. Check for duplicate punches      │
│  3. Validate subscription            │
│  4. Store attendance                 │
│  5. Return ALLOWED / DENIED          │
└──────────┬───────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│  MySQL Database (CleverCloud)        │
│                                      │
│  trn_member_biometric_mappings       │
│  trn_member_attendances              │
│  trn_member_subscriptions            │
└──────────────────────────────────────┘

Three components, two languages, one seamless flow.

🐍 Part 1: The Python Bridge (Gym Laptop Side)

The Problem

The biometric device (a ZK-based fingerprint scanner) is on the gym's local network at 192.168.1.201. It stores fingerprints and punch records internally. It has no concept of "calling a web API."

My Rails app is hosted on Render — a cloud server that the device can't reach directly.

Solution: A Python script that acts as the middleman — reads from the device using the pyzk SDK, and forwards punches to Rails via HTTP.

Configuration

# biometric_bridge/config.py

DEVICE_IP = "192.168.1.201"
DEVICE_PORT = 4370
DEVICE_TIMEOUT = 5

RAILS_API_URL = "https://spine-fitness.com/api/biometric_attendances"
COMP_CODE = "SF"

POLL_INTERVAL_SECONDS = 20

Key decisions:

Port 4370 — Standard ZK biometric device communication port
20-second polling — Balances real-time feel vs. not overwhelming the device
Company code "SF" — Supports multi-tenant architecture (future-proof for multiple gyms)

The Bridge Script

# biometric_bridge/bridge.py

from zk import ZK
import requests
import time
from datetime import datetime
from config import *

def send_to_rails(payload):
    try:
        response = requests.post(
            RAILS_API_URL,
            json=payload,
            timeout=5
        )
        print(f"Sent: {payload} | Response: {response.status_code}")
    except Exception as e:
        print("Rails API error:", e)

def main():
    zk = ZK(
        DEVICE_IP,
        port=DEVICE_PORT,
        timeout=DEVICE_TIMEOUT,
        password=0,
        force_udp=False,
        ommit_ping=False
    )

    print("Connecting to biometric device...")

    try:
        conn = zk.connect()
        conn.disable_device()

        print("Connected to device")
        print("Fetching attendance logs...")

        last_sent = set()

        while True:
            attendances = conn.get_attendance()

            for att in attendances:
                key = f"{att.user_id}-{att.timestamp}"

                # Prevent duplicate sending
                if key in last_sent:
                    continue

                payload = {
                    "compcode": COMP_CODE,
                    "user_id": att.user_id,
                    "timestamp": att.timestamp.strftime("%Y-%m-%d %H:%M:%S"),
                    "device_sn": conn.serial_number
                }

                send_to_rails(payload)
                last_sent.add(key)

            time.sleep(POLL_INTERVAL_SECONDS)

    except Exception as e:
        print("Device connection error:", e)

    finally:
        try:
            conn.enable_device()
            conn.disconnect()
        except:
            pass

if __name__ == "__main__":
    main()

How It Works Step by Step

1. Connect to the device

zk = ZK(DEVICE_IP, port=DEVICE_PORT, timeout=DEVICE_TIMEOUT, ...)
conn = zk.connect()
conn.disable_device()  # Prevents new operations while reading

The pyzk library connects to the ZK device via TCP on port 4370. We temporarily disable the device during reads to prevent data corruption.

2. Poll every 20 seconds

while True:
    attendances = conn.get_attendance()
    # ... process ...
    time.sleep(POLL_INTERVAL_SECONDS)

The script runs in an infinite loop, fetching all attendance records from the device. The device stores punches internally, so we get the full history each time.

3. Deduplicate locally

last_sent = set()

key = f"{att.user_id}-{att.timestamp}"
if key in last_sent:
    continue

Since get_attendance() returns all historical records, we use an in-memory set to track what's already been sent. Only new punches get forwarded. This is deduplication layer 1 — the Rails API has its own deduplication as layer 2.

4. Forward to Rails API

payload = {
    "compcode": COMP_CODE,
    "user_id": att.user_id,
    "timestamp": att.timestamp.strftime("%Y-%m-%d %H:%M:%S"),
    "device_sn": conn.serial_number
}
send_to_rails(payload)

Each punch becomes a clean JSON payload with all the context Rails needs.

Auto-Start on Windows

The gym staff shouldn't need to "start the bridge" manually. A .bat file handles this:

:: biometric_bridge/start_biometric.bat
cd C:\biometric_bridge
python bridge.py

This can be placed in the Windows Startup folder so the bridge starts automatically when the gym opens and the laptop powers on.

Dependencies

# biometric_bridge/requirements.txt
pyzk
requests

Just two dependencies — pyzk for ZK device communication and requests for HTTP calls. Minimal and reliable.

💎 Part 2: The Rails API (Cloud Server Side)

The Route

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    resources :biometric_attendances, only: [:create]
  end
end

This gives us: POST /api/biometric_attendances

The Controller

When the Python bridge sends a punch, the Rails API processes it through a 4-step pipeline:

# app/controllers/api/biometric_attendances_controller.rb

class Api::BiometricAttendancesController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    compcode       = params[:compcode].to_s
    device_user_id = params[:user_id].to_i
    device_sn      = params[:device_sn].to_s
    punch_time     = Time.zone.parse(params[:timestamp]) rescue Time.current

    # ── STEP 1: Find biometric mapping ──
    mapping = TrnMemberBiometricMapping.active.find_by(
      mbm_compcode:       compcode,
      mbm_device_user_id: device_user_id,
      mbm_device_sn:      device_sn
    )

    unless mapping
      render json: {
        status: false,
        message: "Biometric user not mapped"
      }, status: 404
      return
    end

    member = mapping.member

    # ── STEP 2: Ignore duplicate punches (same member, same minute) ──
    if duplicate_punch?(member.id, punch_time)
      render json: { status: true, message: "Duplicate ignored" }
      return
    end

    # ── STEP 3: Validate subscription ──
    subscription = latest_subscription(member.id, compcode)

    if subscription && subscription.ms_end_date >= Date.today
      att_status = "ALLOWED"
      reason     = nil
    else
      att_status = "DENIED"
      reason     = "Subscription expired"
    end

    # ── STEP 4: Store attendance ──
    TrnMemberAttendance.create!(
      att_compcode:       compcode,
      att_member_id:      member.id,
      att_device_user_id: device_user_id,
      att_device_sn:      device_sn,
      att_punch_time:     punch_time,
      att_punch_date:     punch_time.to_date,
      att_status:         att_status,
      att_reason:         reason
    )

    render json: { status: true, access: att_status }
  end

  private

  def duplicate_punch?(member_id, time)
    TrnMemberAttendance.where(
      att_member_id: member_id,
      att_punch_time: time.beginning_of_minute..time.end_of_minute
    ).exists?
  end

  def latest_subscription(member_id, compcode)
    TrnMemberSubscription
      .where(ms_compcode: compcode, ms_member_id: member_id)
      .order(ms_end_date: :desc)
      .first
  end
end

🛡️ Two Layers of Deduplication

This is important — deduplication happens at both levels:

Layer	Where	How	Why
Layer 1	Python bridge	In-memory `set` of `{user_id}-{timestamp}` keys	Prevents resending the same device record on every poll cycle
Layer 2	Rails API	Database query for same member + same minute	Catches duplicates if the bridge restarts (set resets), or if the device sends duplicate records

Member scans finger
       │
       ▼
Python bridge: "Already in last_sent?" ──YES──▶ Skip
       │ NO
       ▼
Rails API: "Punch in same minute?" ──YES──▶ Return "Duplicate ignored"
       │ NO
       ▼
Store attendance ✅

This double-layer approach means the system is resilient to:

Bridge restarts (set clears → Layer 2 catches it)
Device quirks (some ZK devices record multiple entries per scan)
Network retries (if the bridge retries a failed request)

🗄️ Database Design

The Bridge Table: `trn_member_biometric_mappings`

Column	Type	Purpose
`mbm_compcode`	string	Company code (multi-tenant)
`mbm_device_user_id`	integer	User ID on the biometric device
`mbm_device_sn`	string	Device serial number
`mbm_member_id`	integer	FK → `mst_members_lists.id`
`mbm_status`	string	`ACTIVE` / `INACTIVE`

Why is this needed? The biometric device assigns its own user IDs (1, 2, 3...). These don't match your database. This table says "Device user #42 on device SN-ABC = Member Rahul Sharma (ID: 156)".

The Attendance Table: `trn_member_attendances`

Column	Type	Purpose
`att_member_id`	integer	FK → member
`att_device_user_id`	integer	Device user ID
`att_device_sn`	string	Device serial
`att_punch_time`	datetime	Exact punch time
`att_punch_date`	date	For easy date-based queries
`att_status`	string	`ALLOWED` or `DENIED`
`att_reason`	string	Why denied (if applicable)

Key design decision: Even DENIED attempts are stored. This lets the gym owner see which expired members are still trying to come — useful for renewal follow-ups.

🧪 Testing the Full Pipeline

Test with cURL (bypassing the Python bridge)

# Active member
curl -X POST https://spine-fitness.com/api/biometric_attendances \
  -H "Content-Type: application/json" \
  -d '{
    "compcode": "SF",
    "user_id": 42,
    "device_sn": "CRT5200-SN001",
    "timestamp": "2026-03-12 07:30:00"
  }'
# → {"status":true,"access":"ALLOWED"}

# Expired member
# → {"status":true,"access":"DENIED"}

# Unknown biometric ID
# → {"status":false,"message":"Biometric user not mapped"}

Test the Python bridge locally

cd biometric_bridge
pip install -r requirements.txt
python bridge.py
# → Connecting to biometric device...
# → Connected to device
# → Fetching attendance logs...
# → Sent: {...} | Response: 200

🧩 Edge Cases I Solved

Edge Case	Solution
Device returns ALL historical records every poll	Python-side `last_sent` set filters to only new records
Member scans finger 3 times rapidly	Rails-side 1-minute deduplication window
Bridge script crashes / laptop restarts	`.bat` file in Startup folder auto-restarts; Rails Layer 2 catches re-sent duplicates
Gym has multiple devices	`device_sn` is part of the mapping — same user_id on different devices = different members
Timestamp timezone mismatch	`Time.zone.parse` with `rescue Time.current` fallback
Member renews subscription mid-day	`ms_end_date >= Date.today` check means renewal takes effect immediately
Member leaves permanently	Set `mbm_status` to `INACTIVE` — `.active` scope blocks without deleting data
Network/API timeout	Python `requests.post(timeout=5)` with try/except — failed sends are logged, not fatal

📊 How This Powers the Dashboard

All attendance data flows to the admin dashboard in real-time:

🟢 Active members — subscription valid, attendance tracked
🟡 Expiring soon — auto-triggers WhatsApp reminders
🔴 Expired — DENIED attendance logged, visible to gym owner

The gym owner sees a member scan their finger, and within seconds the dashboard reflects it — all without touching a single register.

💡 Key Takeaways

Use a bridge pattern when hardware can't talk to cloud directly. A simple Python script solved the hardware↔cloud gap.
Deduplicate at every layer. Don't trust any single layer to handle it perfectly.
Store denied attempts. They're not failures — they're business intelligence.
Keep the bridge minimal. Two dependencies (pyzk + requests), one config file, one script. Less can go wrong.
Auto-start everything. The gym staff shouldn't need to know Python exists. A .bat file in Startup and it just works.
Multi-language is fine. Python is better at hardware communication (pyzk), Rails is better at web apps. Use the right tool for each layer.

🏁 Conclusion

This feature taught me that production software often lives at the intersection of hardware and software. The biometric device, the Python bridge, the Rails API, and the MySQL database — four different technologies working together to create a seamless experience: member scans finger → attendance appears on dashboard.

The most satisfying moment? Watching the gym owner check the dashboard and see real-time attendance without touching a single notebook.

🔗 Live App: spine-fitness.com
💻 Full Source Code: GitHub
📂 Python Bridge Code: biometric_bridge/

Found this useful? Drop a ❤️! Got questions about biometric integration or the Python bridge? Let's chat in the comments!

How I Ditched Interakt and Built a Direct WhatsApp Automation Pipeline with Meta Cloud API

Lakshay Tyagi — Thu, 07 May 2026 05:30:18 +0000

Originally published on Hashnode

A follow-up to my previous post on building Spine Fitness — a production gym management system used by 200+ members daily.

👉 In this post, I’ll walk through why I replaced Interakt with Meta Cloud API, the issues I faced, and how I built a reliable, production-ready WhatsApp automation pipeline.

The Backstory

A few months ago, I published a post about building Spine Fitness — a full-stack gym management system I deployed for a real gym in Dwarka, New Delhi. The system replaced physical notebooks with a Rails app that handled member management, biometric attendance, payments, and WhatsApp notifications.

In that post, I mentioned using Interakt as the WhatsApp API provider.

I no longer use Interakt.

This is the story of why I switched, the absolute nightmare of dealing with Meta's ecosystem, and how I eventually built a clean, direct integration with Meta Cloud API — from scratch — that now reliably sends automated membership reminders to gym members every morning at 10 AM IST.

What Was Working Before (And What Wasn't)

The Interakt setup seemed fine on paper. I had:

A connected WhatsApp number (8920)
Approved message templates
A Rails service (Interakt::SendWhatsapp) making API calls
A cron job firing daily at 10 AM
A trn_whatsapp_logs table logging every attempt

But when I checked the logs, something was wrong.

Every single message had wl_status = 'QUEUED'. No delivered. No read. Just QUEUED — forever.

SELECT wl_status, COUNT(*) FROM trn_whatsapp_logs GROUP BY wl_status;
-- QUEUED: 13
-- DELIVERED: 0
-- READ: 0

Interakt's dashboard showed messages going out. Single tick on WhatsApp. Members never received anything.

I contacted Interakt support. They said the number would be removed from their system. Weeks passed. It wasn't removed. Meanwhile, messages kept getting queued and silently dropped.

I decided to move on.

The Plan: Go Direct with Meta Cloud API

Instead of relying on a BSP (Business Solution Provider) like Interakt, I'd connect directly to Meta's WhatsApp Cloud API. Same infrastructure the big players use — no middleman, full control.

The plan was simple:

Register 8920 on Meta Cloud API
Create message templates
Replace Interakt::SendWhatsapp with Meta::SendWhatsapp in Rails
Set up a webhook for delivery status updates

Simple in theory. Absolutely chaotic in practice.

Week One: The Meta Setup Maze

Haptik Was Everywhere

When I logged into Meta Business Manager, I found that both my numbers (7011 and 8920) had Haptik (Interakt's parent company) as a partner with full control. Even after Interakt said they removed 8920, Haptik still appeared in the partners tab.

This meant any attempt to register 8920 directly on Meta Cloud API failed with:

"Unsupported post request. Object with ID '1073316579198774' does not exist,
cannot be loaded due to missing permissions..."

The number existed. It just wasn't mine yet.

The Payment Method Loop

After finally getting Interakt to release 8920, I tried adding a payment method to the WhatsApp Business Account. Meta charged my card ₹3 as verification — four separate times — and never actually saved it.

The Developer Console kept screaming "Missing valid payment method" even after the WABA settings clearly showed Visa ****4009 as default. I eventually realized this was a Meta UI bug specific to India accounts. The payment was there. The console just couldn't see it.

The Display Name That Wouldn't Approve

I registered 8920 on Meta Cloud API and submitted "Spine Fitness" as the display name. It went into PENDING_REVIEW.

It stayed there for two days.

Then it came back as DECLINED.

Apparently "Spine Fitness" was too generic. Meta's guidelines require the display name to clearly and uniquely represent your business. I resubmitted as "Spine Fitness Gym Dwarka" — specific enough to pass their guidelines — and it was approved within hours.

The Code Change: Surprisingly Clean

Once the Meta side was sorted, the Rails code change was actually minimal. I created a new service file:

# app/services/meta/send_whatsapp.rb
module Meta
  class SendWhatsapp
    API_URL = "https://graph.facebook.com/v19.0"

    def self.send_template(phone:, template:, body_values:)
      phone = phone.to_s.gsub(/\D/, "").last(10)
      return { http_code: 0, body: {}, raw: "Invalid phone" } unless phone.length == 10

      uri = URI("#{API_URL}/#{ENV['WHATSAPP_PHONE_ID']}/messages")

      payload = {
        messaging_product: "whatsapp",
        to: "91#{phone}",
        type: "template",
        template: {
          name: template,
          language: { code: "en" },
          components: [{
            type: "body",
            parameters: body_values.map { |v| { type: "text", text: v.to_s } }
          }]
        }
      }

      http = Net::HTTP.new(uri.host, uri.port)
      http.use_ssl = true
      request = Net::HTTP::Post.new(uri)
      request["Authorization"] = "Bearer #{ENV['WHATSAPP_TOKEN']}"
      request["Content-Type"] = "application/json"
      request.body = payload.to_json

      response = http.request(request)
      parsed_body = JSON.parse(response.body) rescue {}
      { http_code: response.code.to_i, body: parsed_body, raw: response.body }
    end
  end
end

And changed one line in the job:

# Before
response = Interakt::SendWhatsapp.send_template(...)

# After
response = Meta::SendWhatsapp.send_template(...)

Two environment variables on Render:

WHATSAPP_PHONE_ID=1073316579198774
WHATSAPP_TOKEN=<permanent system user token>

That was it for the sending side.

The Template Problem: Meta Hates "Renew Now"

My original template said:

"Hi {{1}}, your membership at Spine Fitness expires on {{2}}. Renew now to avoid interruption. Contact us or visit the gym."

Meta flagged it as Marketing. Every rewrite got flagged. Anything with "renew", "visit us", or "contact us" triggered the marketing classifier.

The fix was to make it purely transactional — no call to action, no promotional language:

"Your membership at Spine Fitness (ID: {{1}}) will expire on {{2}}. This is an automated notification."

Boring? Yes. Approved as Utility? Also yes. And Utility templates are cheaper and have fewer delivery restrictions than Marketing ones.

The Delivery Problem: App Was Unpublished

After all of this, messages were still only delivering to numbers that had previously messaged 8920 first. My number worked. My mother's worked (after she sent "Hi" to 8920 first). Everyone else got accepted by the API but never actually received the message.

I spent a long time chasing the wrong culprits — display name status, payment method, credit lines, contact book theory. The actual reason was simpler and more embarrassing:

My Meta Developer App was unpublished.

In development mode, WhatsApp API has severe restrictions on who can receive messages. The moment I published the app (which required adding a privacy policy URL, an app icon, and completing app review), messages started going to everyone — no prior interaction required.

That single toggle fixed what two weeks of debugging couldn't.

Adding Webhook Delivery Tracking

With Interakt, I never got real delivery status back. With Meta, I could set up a webhook to receive sent, delivered, and read status updates in real time.

# app/controllers/webhooks/meta_controller.rb
class Webhooks::MetaController < ApplicationController
  skip_before_action :verify_authenticity_token

  def verify
    mode      = params['hub.mode']
    token     = params['hub.verify_token']
    challenge = params['hub.challenge']

    if mode == 'subscribe' && token == ENV['WHATSAPP_WEBHOOK_TOKEN']
      render plain: challenge, status: :ok
    else
      head :forbidden
    end
  end

  def receive
    body = JSON.parse(request.body.read)
    entries = body.dig('entry') || []

    entries.each do |entry|
      entry.dig('changes')&.each do |change|
        change.dig('value', 'statuses')&.each do |status|
          process_status(status)
        end
      end
    end

    head :ok
  rescue => e
    Rails.logger.error "[MetaWebhook] Error: #{e.message}"
    head :ok
  end

  private

  def process_status(status)
    message_id = status['id']
    status_val = status['status']&.upcase
    return unless message_id.present?
    return unless %w[DELIVERED READ FAILED SENT].include?(status_val)

    log = TrnWhatsappLog.find_by(wl_interakt_msg_id: message_id)
    return unless log

    case status_val
    when 'DELIVERED'
      log.update!(wl_status: 'DELIVERED', wl_delivered_at: Time.current)
    when 'READ'
      log.update!(wl_status: 'READ', wl_read_at: Time.current)
    when 'FAILED'
      error = status.dig('errors', 0, 'message') || 'Unknown error'
      log.update!(wl_status: 'FAILED', wl_failed_reason: error)
    end

    Rails.logger.info "[MetaWebhook] Updated log #{log.id} → #{status_val}"
  end
end

One important step that wasn't obvious from the docs — I had to explicitly subscribe my app to the correct WABA via API:

curl -X POST \
  "https://graph.facebook.com/v19.0/1603252984268401/subscribed_apps" \
  -H "Authorization: Bearer YOUR_TOKEN"

Without this, the webhook configuration in the Developer Console subscribes to the test WABA, not your production one. Real delivery events never arrive.

Once subscribed correctly, the logs updated in real time:

[MetaWebhook] Updated log 30 → READ
[MetaWebhook] Updated log 32 → READ

The Final State

Here's what the full pipeline looks like now:

cron-job.org (daily 4:30 UTC / 10:00 AM IST)
    │
    ▼
GET /cron/send_expiry_whatsapp
    │
    ▼
MembershipExpiryWhatsappJob (:expiring / :expired)
    │
    ├── Query members expiring in 3 days (or already expired)
    ├── Skip if already DELIVERED or READ
    ├── Call Meta Cloud API
    ├── Log response to trn_whatsapp_logs (status: QUEUED)
    │
    ▼
Meta WhatsApp Cloud API
    │
    ▼
Member's WhatsApp (message delivered)
    │
    ▼
POST /webhooks/meta (delivery status webhook)
    │
    ▼
trn_whatsapp_logs updated: QUEUED → DELIVERED → READ

And the numbers after going live:

Metric	Interakt	Meta Cloud API
Messages delivered	0	✅ All
Status tracking	❌ Never updated	✅ Real-time
Cost per message	~₹0.30 + BSP fee	₹0.12 (utility)
Cold outreach	❌ Broken	✅ Works
Setup pain	Low	Very high

What I'd Tell Myself Before Starting

1. Go direct from the start. BSPs like Interakt add cost and a dependency. If you're building something custom, Meta Cloud API gives you full control and better pricing.

2. Publish your app early. The development mode restriction is the least documented and most impactful limitation. You'll waste days debugging delivery issues that disappear the moment you go live.

3. Display names matter more than you think. Generic names get declined. Be specific — include your city, your category, something that makes the name uniquely yours.

4. Subscribe your webhook to the right WABA. The Developer Console subscribes to the test WABA by default. Make the API call to subscribe your production WABA explicitly.

5. Use Utility templates, not Marketing. Avoid action words. Make it sound like a system notification. It's cheaper and has fewer delivery restrictions.

What's Next

The automation is live and running daily. Members are receiving expiry reminders automatically. The gym owner stopped making manual phone calls.

Next up: a member-facing view so members can check their own subscription status, and SMS fallback for members not on WhatsApp.

Spine Fitness is live at spine-fitness.com. Source code on GitHub.

If you found this useful — or if you've been through the Meta API maze yourself — drop a comment. I'd love to hear your war stories.

Step-by-step Installation guide for Ruby

Lakshay Tyagi — Sun, 02 Nov 2025 01:49:57 +0000

Installing Ruby on Xubuntu (My Notes from The Odin Project)

Before jumping into Ruby on Rails, we first need to set up Ruby itself.

It sounds simple, but trust me — this step can get messy if you skip details.

I went through this recently while following The Odin Project, and here’s a cleaner, beginner-friendly walkthrough based on my own experience.

Why You Need Ruby First

Rails runs on Ruby, so before creating your first app, you need the correct Ruby version and a version manager to switch between them easily.

I’ll be using rbenv, which helps install and manage Ruby versions safely without touching system files.

Step 1: Update Your System

Always start fresh!

Open your terminal (Ctrl + Alt + T on Xubuntu) and update existing packages:

sudo apt update && sudo apt upgrade

This ensures your system’s libraries are current.
You’ll be asked for your password and to confirm updates — press Y when prompted.

Step 2: Install Required Dependencies

Ruby needs a few libraries and tools to build properly:

sudo apt install gcc make libssl-dev libreadline-dev zlib1g-dev libsqlite3-dev libyaml-dev

💡 Linux Tip:
Ctrl + Shift + C → Copy from terminal
Ctrl + Shift + V → Paste into terminal

Step 3: Install rbenv

rbenv lets you install and switch between Ruby versions easily.

Clone it from GitHub:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv

Then initialize it:

~/.rbenv/bin/rbenv init

Now close your terminal and reopen it to refresh your environment variables.

Verify installation:

rbenv -v

You should see something like:
rbenv 1.x.x

Step 4: Add ruby-build Plugin

This plugin helps rbenv compile and install Ruby versions.

mkdir -p "$(rbenv root)"/plugins
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

Now rbenv can handle Ruby installations.

Step 5: Install Ruby

We’re finally ready! Run:

rbenv install 3.4.2 --verbose

⏳ This might take 10–15 minutes.
The --verbose flag lets you see progress so you know it hasn’t frozen.

If you get an error like:

ruby-build: definition not found: 3.4.2

Update ruby-build and try again:

git -C "$(rbenv root)"/plugins/ruby-build pull

Step 6: Set Default Ruby Version

Once installation completes, set it as your global Ruby version:

rbenv global 3.4.2

Verify with:

ruby -v

If everything worked, you’ll see something like:

ruby 3.4.2pXXX (20XX-XX-XX revision XXXXX) [x86_64-linux]

🎉 Congrats — you’ve officially installed Ruby!

What’s Next

With Ruby set up, you’re ready to install Rails and start building your first app.
You can also watch my video walkthrough of this process here 🎥 — [YouTube Link].

Credits

This post is inspired by The Odin Project’s “Installing Ruby” lesson.
I followed their guidance but rewrote this post based on my own notes and experience using Xubuntu Linux.