DEV Community: Renzo Diaz

Build a Secure API with Rails 8 - Part-2: Authentication Foundations

Renzo Diaz — Wed, 13 May 2026 16:44:18 +0000

Hey folks 👋

Welcome back. In Part 1 we walked through the 11 attack vectors that shape every decision in this series. If you skipped it, please go read it first, because everything we do from now on is a direct response to one of those threats. Without that context, the code below is just another tutorial.

In this part we are going to start writing the API. By the end you will have a Rails 8 project with user registration, login, and token-based authentication using OAuth2 + JWT, with tokens stored safely in HttpOnly cookies instead of localStorage.

I want to be honest about something. When I first built this, I tried to do "everything at once". I added authentication, authorization, rate limiting, and serializers in the same commit, and I got lost. So in this series we are going slow on purpose. Part 2 is only about laying the foundation correctly. We will not finish every mitigation today, and that's fine.

To help us stay oriented, I'll keep a small progress tracker at the end of each post.

What we are building in Part 2

A small Rails 8 API with:

A User model with hashed passwords (no plain text, ever)
OAuth2 password grant flow so the client can exchange email + password for a token
JWT access tokens that the server can verify without hitting the database
Refresh tokens with short-lived access tokens
Tokens delivered through encrypted HttpOnly cookies, not JSON bodies the frontend has to store manually

If you've never touched Devise or Doorkeeper before, don't worry. I'll explain why we use each piece, not just how.

Prerequisites

Ruby on Rails 8
PostgreSQL 14+
Postman, Insomnia, or curl for testing

Step 1. Create the project in API mode

Rails has a built-in flag to skip all the browser-only middleware (cookies are gone by default, ERB views are gone, asset pipeline is gone). That's what we want for an API.

rails new secure_api_auth -T -d postgresql --api

Breaking that down:

-T skips the default test suite (we'll set up testing later in the series)
-d postgresql uses Postgres instead of SQLite
--api strips out browser-oriented middleware

Then:

cd secure_api_auth

Tip from experience: commit right here as "Initial commit" before you change anything. When something breaks two hours from now, having a clean baseline to git diff against will save you.

Step 2. Add the gems we need

Open your Gemfile and add:

# Database
gem 'pg'

# Password hashing
gem 'bcrypt', '~> 3.1.7'

# Authentication & Authorization
gem 'devise'
gem 'doorkeeper'
gem 'doorkeeper-jwt'

Then:

bundle install

A quick mental model before we go further, because these three gems confused me for a long time:

Devise owns the user identity. It knows how to store a user, hash a password, and verify "is this the right password for this email?"
Doorkeeper owns the access decision. After Devise confirms who you are, Doorkeeper issues the token that proves you are allowed to call the API.
doorkeeper-jwt changes the format of that token from a random string to a JWT, so the server can verify it without a database lookup.

In other words: Devise checks the ID at the door, Doorkeeper hands you the wristband, and JWT is what the wristband is made of.

Step 3. Install Devise

bin/rails generate devise:install

Devise will print a few setup instructions. Since we're API-only, we only care about one of them: setting the default URL options for development.

Open config/environments/development.rb and add:

config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }

We won't be sending real emails in this tutorial, but Devise complains if this isn't set.

Generate the User model

bin/rails generate devise User
bin/rails db:migrate

This creates a users table with an encrypted_password column (and a few others for tracking sign-in counts and lockouts).

🛡️ Mitigation in action: Token Theft and Password Breaches (Part 1, vectors 4 and 10)

Devise hashes passwords with bcrypt, which is intentionally slow. Even if an attacker dumps your database, they can't reverse the hashes. Each password also gets a unique salt, so two users who pick the same password end up with completely different hashes. This is why we never, ever store passwords in plain text.

Switch Devise to API mode

By default Devise wants to redirect users to HTML pages after login. We need to turn that off.

Open config/initializers/devise.rb and add (or modify) these two lines:

Devise.setup do |config|
  # ... keep everything else as generated ...

  # Don't use session storage for API authentication
  config.skip_session_storage = [:http_auth, :params_auth]

  # No HTML redirects, we return JSON
  config.navigational_formats = []
end

Step 4. Install Doorkeeper

bin/rails generate doorkeeper:install
bin/rails generate doorkeeper:migration

Before we run that migration, we need to edit it. Doorkeeper is built for the full OAuth2 flow (the one where you click "Log in with GitHub" and get redirected). We don't need that. We need the simpler password grant flow, where the client sends email + password directly and gets a token back. That requires loosening two null: false constraints.

Open the generated migration file (something like db/migrate/XXXXX_create_doorkeeper_tables.rb):

# In the oauth_applications table: allow null redirect_uri
t.text :redirect_uri  # remove the `null: false`

# In the oauth_access_tokens table: allow null application reference
t.references :application  # remove the `null: false`

# At the bottom of the file, link tokens back to users
add_foreign_key :oauth_access_grants, :users, column: :resource_owner_id
add_foreign_key :oauth_access_tokens, :users, column: :resource_owner_id

Then migrate:

bin/rails db:migrate

A word on the password grant flow. The OAuth2 spec actually discourages this flow for third-party clients, because it requires the client to handle the user's raw password. But for first-party clients (your own mobile app, your own SPA), it's perfectly reasonable, and it's what most "log in with email and password" APIs do under the hood. The key word is first-party: you control both ends.

Step 5. Re-enable cookies in API mode

This is the part that surprised me the first time. When you pass --api to rails new, Rails removes the cookie middleware. That makes sense, an API doesn't usually need cookies. But we do want them, because we want to store the access token in an HttpOnly cookie instead of letting JavaScript handle it.

Open config/application.rb:

module SecureApiAuth
  class Application < Rails::Application
    config.load_defaults 8.0
    config.api_only = true

    # Re-add cookie middleware so we can use HttpOnly cookie auth
    config.middleware.use ActionDispatch::Cookies
    config.middleware.use ActionDispatch::Session::CookieStore,
                          key: '_secure_api_session',
                          same_site: :lax,
                          secure: Rails.env.production?
  end
end

🛡️ Mitigation in action: XSS and Token Theft (Part 1, vectors 1 and 10)

This is the single most important decision in this whole post. If you store a JWT in localStorage, any piece of JavaScript that runs on your page can read it. One XSS bug, one compromised npm dependency, one browser extension, and the token is gone.

HttpOnly cookies are invisible to JavaScript. The browser sends them automatically with every request, but document.cookie will not show them. Secure ensures the cookie is only sent over HTTPS. SameSite=Lax is our first line of defense against CSRF (which we'll fully address in a later part).

Step 6. Teach Doorkeeper to read tokens from the cookie

Out of the box, Doorkeeper looks for tokens in the Authorization: Bearer ... header. We need to add a new place for it to look: our encrypted cookie.

Create lib/doorkeeper/from_cookie.rb:

module Doorkeeper
  module FromCookie
    module_function

    def call(request)
      # Read the encrypted access token from the HttpOnly cookie
      request.cookie_jar.encrypted[:access_token]
    end
  end
end

Why encrypted and not just signed?

Rails offers two protected cookie jars: signed (tamper-proof but readable) and encrypted (tamper-proof AND unreadable). If someone opens DevTools and copies the raw cookie value, with signed they'd see the JWT in plain text. With encrypted they see AES-256 garbage. The JWT is already protected by its own signature, but defense in depth is cheap here, so we use encrypted.

Step 7. Configure Doorkeeper

Open config/initializers/doorkeeper.rb and replace the generated content with:

# frozen_string_literal: true

require_relative '../../lib/doorkeeper/from_cookie'

Doorkeeper.configure do
  orm :active_record
  api_only

  # Resource Owner Password Credentials grant.
  # Lets users log in with email + password directly.
  grant_flows %w[password]
  allow_blank_redirect_uri true

  # How to find the user when they log in.
  resource_owner_from_credentials do |_routes|
    user = User.find_for_database_authentication(email: params[:email])
    user if user&.valid_password?(params[:password])
  end

  skip_client_authentication_for_password_grant true

  # Short-lived access tokens.
  access_token_expires_in 15.minutes

  # Enable refresh tokens.
  use_refresh_token

  # Use JWT format for access tokens.
  access_token_generator 'Doorkeeper::JWT'

  # Scopes. We'll use these later for authorization.
  default_scopes :read
  optional_scopes :write, :admin

  base_controller 'ApplicationController'

  # Token lookup order: 1) our cookie, 2) Bearer header, 3) query param.
  access_token_methods Doorkeeper::FromCookie,
                       :from_bearer_authorization,
                       :from_access_token_param
end

A few of these settings deserve a closer look:

access_token_expires_in 15.minutes is intentional. If a token leaks, the attacker only has 15 minutes before it stops working. The refresh token (which lives longer) covers the user experience side, so they don't have to log in every 15 minutes.

use_refresh_token enables the rotation pattern: when an access token expires, the client uses a refresh token to get a new one without prompting the user. We'll wire up rotation more carefully in a later part.

access_token_methods order matters here. Doorkeeper checks the cookie first, then the Authorization header, then a query parameter. In production I'd actually remove from_access_token_param because tokens in URLs end up in server logs and browser history (Part 1, vector 10). For now I'm leaving it in so you can test easily with curl, but treat it as a TODO.

🛡️ Mitigation in action: Token Theft (Part 1, vector 10)

Short access token lifetime plus refresh token rotation is the standard pattern for limiting blast radius when a token leaks. We'll harden this further by adding revocation when we build the /logout endpoint.

Step 8. Configure the JWT payload

Create config/initializers/doorkeeper_jwt.rb:

Doorkeeper::JWT.configure do
  # Sign tokens with HS256 using the app's secret key.
  secret_key Rails.application.credentials.secret_key_base
  signing_method :hs256

  token_payload do |opts|
    user = User.find(opts[:resource_owner_id])

    {
      iat: Time.current.to_i,                        # Issued at
      exp: (Time.current + opts[:expires_in]).to_i,  # Expires at
      jti: SecureRandom.uuid,                        # Unique token ID
      sub: user.id,                                  # Subject (user ID)
      email: user.email,
      scopes: opts[:scopes]
    }
  end

  secret_key_path nil
  use_application_secret false
end

If you've never seen a JWT before, here's the short version. A JWT is three base64-encoded parts joined by dots:

header.payload.signature

The header says how the token is signed. The payload is the JSON we just defined above (user ID, email, expiry, etc). The signature is a hash of header.payload combined with our secret key. If an attacker changes anything in the payload, the signature won't match anymore and the token is rejected.

The jti (JWT ID) is worth flagging. It's a unique ID per token, which we'll use later when we implement token revocation. You "blacklist" the jti instead of trying to delete the JWT itself (you can't, the client has it).

Where we are right now

We have a Rails 8 API with a User model, password hashing, OAuth2 password grant, JWT access tokens, refresh tokens, and HttpOnly cookie storage. That's a solid foundation.

But we have not written the controllers yet (register, login, logout, refresh, "who am I"). That's coming in Part 3, along with the first set of mitigations that depend on having endpoints to protect.

Progress tracker: security vectors from Part 1

I'll keep this table updated in every part so you can see exactly what's covered and what's still pending.

#	Attack vector	Status	Where
1	XSS	🟡 Partially mitigated	`HttpOnly` cookie storage (Step 5). Full content sanitization is a frontend concern.
2	SQL Injection	🟢 Mitigated by default	Active Record's `find_by`, `where`, etc. We'll still review controllers in Part 3.
3	CSRF	🔴 Not yet	`SameSite=Lax` is set, but we need explicit CSRF tokens for cookie auth. Part 3.
4	Brute Force	🟡 Partially mitigated	bcrypt slows password cracking. Rate limiting with `Rack::Attack` comes in Part 4.
5	User Enumeration	🔴 Not yet	We need to design login/reset responses to be uniform. Part 3.
6	IDOR	🔴 Not yet	Will be addressed when we add resources + Pundit/Sqids. Part 5.
7	Mass Assignment	🔴 Not yet	Strong params, controller by controller. Part 3.
8	Excessive Data Exposure	🔴 Not yet	Serializers (JSON:API or `alba`). Part 3.
9	MITM	🟡 Partially mitigated	`secure: true` on cookies in production. `force_ssl` and HSTS come in Part 4.
10	Token Theft	🟢 Mostly mitigated	`HttpOnly` + encrypted cookies + short-lived tokens + refresh tokens. Revocation in Part 3.
11	Verbose Error Messages	🔴 Not yet	Production error handling. Part 4.

Legend: 🟢 Covered, 🟡 Partial, 🔴 Pending

Coming up in Part 3

We'll build the actual auth controllers (register, login, logout, refresh, and me), and while we do it we'll knock out four more vectors from the tracker: CSRF, User Enumeration, Mass Assignment, and Excessive Data Exposure.

If this helped you, follow along so you don't miss it. And if anything is unclear, drop a comment, I read all of them.

Build a Secure API with Rails 8 - Part-1

Renzo Diaz — Wed, 06 May 2026 23:14:19 +0000

Hi folks👋!

In this post I want to share something I wish I had when I started building APIs with Ruby on Rails: a practical guide that takes security seriously from the beginning.

When I built my first REST API, most tutorials I found were focused on getting something running quickly. They were great for learning the basics, but they usually skipped important topics like API versioning, authentication strategy, authorization, and security.

Even when using AI tools to generate a “secure API”, the result is often still insecure unless you already understand the threats you are trying to protect against. Security is not something you get automatically. You need to know what problems you are solving and why the protections matter.

I ended up reading API design books, OWASP documentation, and real-world breach reports before I finally felt like I understood what I was building, I've put all in practice. This post is the guide I wish I had back then.

In this series we are going to build a production-ready Rails 8 API with authentication, authorization, rate limiting, secure cookies, security headers, and other important protections. I also want to explain the reasoning behind each decision, not just copy-paste code without context.

Before writing any code, let’s first understand the main attack vectors we need to defend against.

The attack vectors we are defending against

1. XSS (Cross-Site Scripting)

🚨 Threat:
XSS happens when an attacker injects malicious JavaScript into content that later gets rendered in another user’s browser. In API-driven applications, one of the biggest risks is token theft. If JWTs are stored in localStorage, a malicious script can read and steal them immediately.

🛡️ Mitigation:
Avoid storing authentication tokens in localStorage or other browser-accessible storage. Instead, store them in secure HttpOnly cookies so JavaScript cannot access them. Cookies should also use the Secure and SameSite attributes. Any user-generated content rendered in the frontend should be properly escaped or sanitized.

2. SQL Injection

🚨 Threat:
SQL Injection happens when user input is inserted directly into a SQL query without proper sanitization. An attacker can manipulate the query to bypass authentication, read sensitive data, or modify the database.

🛡️ Mitigation:
Avoid interpolating user input directly into SQL queries. In Rails, prefer Active Record methods like where, find_by, and parameterized queries, which automatically sanitize input. If raw SQL is unavoidable, use bound parameters instead of string interpolation. You should also validate input, use strong parameters, and follow the principle of least privilege for database accounts.

3. CSRF (Cross-Site Request Forgery)

🚨 Threat:
CSRF happens when a malicious website tricks a logged-in user’s browser into sending authenticated requests to your application using automatically attached cookies.

This is especially important in Rails APIs using session cookies or JWTs stored in HttpOnly cookies. Even though JavaScript cannot read those cookies, the browser still sends them automatically with requests.

An attacker could potentially trigger actions like changing account settings, creating resources, or deleting data without the user realizing it.

🛡️ Mitigation:
Enable CSRF protection for any cookie-based authentication flow. In Rails, use protect_from_forgery and require valid CSRF tokens for state-changing requests like POST, PUT, PATCH, and DELETE.

Authentication cookies should also use:

HttpOnly
Secure
SameSite=Lax or SameSite=Strict

You should also validate Origin and Referer headers and keep CORS restricted to trusted frontend domains.

If the browser automatically sends authentication, CSRF protection still matters, even if the API itself is technically stateless.

4. Brute Force

🚨 Threat:
Brute force attacks happen when an attacker repeatedly tries large numbers of username and password combinations against your login endpoint.

This commonly targets login forms, password reset endpoints, and authentication APIs. Successful attacks can lead to account compromise, credential stuffing, and unnecessary server load.

🛡️ Mitigation:
Use rate limiting on authentication-related endpoints. In Rails, tools like Rack::Attack can throttle repeated requests by IP address, email, or both.

You should also:

temporarily lock accounts after repeated failures
require strong passwords
detect suspicious login activity
avoid revealing whether an account exists
consider CAPTCHA or step-up verification after suspicious behavior

5. User Enumeration

🚨 Threat:
User enumeration happens when an application reveals whether an account exists through different error messages.

For example:

“Email not found”
“Incorrect password”

An attacker can use these differences to discover valid accounts and later target them with brute force attacks, phishing, or credential stuffing.

🛡️ Mitigation:
Return consistent responses during login, password reset, and account recovery flows.

Instead of exposing whether the email exists, use generic responses such as:

“Invalid credentials”
“If an account exists, instructions have been sent”

You should also rate limit these endpoints and monitor repeated probing attempts.

6. IDOR (Insecure Direct Object Reference)

🚨 Threat:
IDOR happens when users can access resources they do not own by changing identifiers in URLs or request parameters.

For example:


User.find(params[:id])

If ownership checks are missing, changing /users/42 to /users/43 could expose another user’s data.

🛡️ Mitigation:
Always scope records through the authenticated user or an authorization policy.

Instead of:


Post.find(params[:id])

Prefer:


current_user.posts.find(params[:id])

Authorization libraries like Pundit or CanCanCan also help enforce access rules consistently across the application. I also avoid exposing raw database IDs directly to the frontend. Instead, I use Sqidsto generate less predictable public IDs, which helps reduce simple enumeration attacks.

7. Mass Assignment

🚨 Threat:
Mass assignment happens when the application accepts user input and blindly assigns it to model attributes.

An attacker could submit unexpected fields such as:


{

  "admin": true

}

If those fields are not filtered properly, the attacker may gain elevated privileges or modify protected data.

🛡️ Mitigation:
Use strong parameters in every controller.

In Rails, always whitelist allowed attributes using:


params.require(:user).permit(:email, :password)

Never pass raw params directly into create or update.

Sensitive fields like roles, permissions, ownership fields, or account status flags should never be user-assignable.

8. Excessive Data Exposure

🚨 Threat:
Excessive data exposure happens when an API returns more information than the client actually needs.

This often happens when entire Active Record objects are rendered directly into JSON responses.

Sensitive data such as password digests, internal IDs, permissions, API keys, or private metadata may accidentally leak through the API.

🛡️ Mitigation:
Only return the fields the client actually needs.

Instead of blindly rendering full objects:


render json: @user

Use serializers or custom JSON responses that explicitly define safe attributes.

Sensitive fields should never appear in API responses.

You should also regularly review serialized responses to make sure no internal data is leaking unintentionally.

9. MITM (Man-in-the-Middle)

🚨 Threat:
A Man-in-the-Middle attack happens when an attacker intercepts traffic between the client and server.

Without HTTPS, credentials, tokens, cookies, and other sensitive data can travel in plain text and be stolen or modified.

Attackers on the same network, malicious proxies, or compromised routers can hijack sessions or impersonate users.

🛡️ Mitigation:
Always enforce HTTPS.

In Rails, enable:


config.force_ssl = true

This redirects insecure requests and ensures cookies are only sent over encrypted connections.

Authentication cookies should also use the Secure and HttpOnly flags.

You should additionally enable HSTS headers and avoid loading insecure mixed-content resources.

10. Token Theft

🚨 Threat:
Token theft happens when an attacker gains access to a valid authentication token and uses it to impersonate a user.

Stolen JWTs can come from XSS attacks, insecure storage, leaked logs, browser extensions, compromised devices, or intercepted traffic.

If tokens remain valid for a long time, the attacker may keep access even after the user notices something is wrong.

🛡️ Mitigation:
Reduce token exposure and keep token lifetimes short.

Prefer storing tokens in secure HttpOnly cookies instead of localStorage.

Use:

short-lived access tokens
refresh token rotation
token revocation mechanisms

You should also avoid exposing tokens in logs or URLs and protect the application against XSS vulnerabilities.

11. Verbose Error Messages

🚨 Threat:
Verbose error messages expose internal application details to attackers.

Stack traces, database errors, framework versions, SQL queries, and file paths can all help attackers understand how the system works and make exploitation easier.

🛡️ Mitigation:
Production applications should return generic and safe error responses.

Instead of exposing internal exceptions, return messages such as:

Internal Server Error
Invalid request

Detailed errors should only be logged internally for debugging.

In Rails, make sure debug pages and detailed exceptions are disabled in production.

Final Thoughts

These are some of the most important security risks to think about when building APIs, and we will revisit them throughout this series as we implement each feature step by step.

In Part 2 we will start building the Rails 8 API from scratch and set up the project foundation correctly from the beginning, including authentication, secure configuration, and API structure.

Follow along if you want to get notified when the next part is published.

What are my day-to-day tools as a full-stack developer?

Renzo Diaz — Sat, 20 Jun 2020 00:26:50 +0000

I've divided a list of tools that I use every day working as a full-stack developer by category.

Design

Graphic link:

I can't afford Illustrator monthly so I found this alternative, I paid once and it worth all. I can edit vectors, AI files, export everything that you can do with Illustrator.

SketchApp link:

When it comes to design mockups I use Sketch, it has a friendly interface that makes it easy to design.

Zeplin link:

If you are developing an application you should have quick access to the mockup assets like images, colors, icons, etc. Zeplin is a design collaboration tool that allows uploading your mockups to the cloud you all the development team can access them quickly and easily.

Development

Iterm2 link

An alternative to default terminal on macOS

Vim link

I use Vim as the code editor, I've customized shortcuts and plugins for fast development.

Docker link

Docker to containerize my apps

Xcodelink

When I need to develop an IOS app I use Xcode with Swift.

TMUX link

When I'm developing a web application I need quick access to different terminals, for example, to run a server, to use my Vim editor all in just one terminal in a single session.

Homebrew link

A package manager for macOS.

Repl link

Sometimes I need to write quick methods to see what returns on the console.

Services

Gitlab link

I'm a fan of Gitlab, private repositories, CI/CD and you can also use the community edition to install in your own server.

HEROKU link

Where I deploy my personal projects.

AWS S3 link

When I'm working on a big application I store the resources in a bucket in AWS S3, and when I need to create a CDN as well.

PivotalTracker link

Every developer should use a tool to track progress on the development or specific task, I use PivotalTracker for big projects and Gitlab board for small.

Utilities

1Password: My generate and store passwords.
Boostnote: Save my snippets or documentation.
Workspace: I organize my apps in workspaces, so I can access them in one click.
Toggle Alfred: Enhanced spotlight in mac.
ExpressVPN: A VPN to navigate safely.

I'm not a Rich guy that can afford a Mac, I use a Mac because I feel more comfortable work design, develop Web and iOS applications. I work for years to get a MacBook 2017 before I used to go to my university to use design tools.

I would appreciate it if you can share the tools you use in your day-to-day.

Have a nice day!

How to use ULID as primary key Rails

Renzo Diaz — Thu, 21 May 2020 19:54:29 +0000

A short story

Ruby on Rails is a powerful framework it is easy to create APIs and fast website development, one thing that came when I was developing an API was how to change the Integer auto-increment primary key because having a predictable Id can be risky in terms of security if you share it for a client-size application, the user can guess ids and modify the database in the worst of the case, at that moment I had to research some alternatives and I found UUID a non-sequential data type that can be easily be implemented in Rails, so I've tried it and everything was ok until I had to sort ASC and DESC, I realize that the methods Model.first and Model.last doesn't work as expected because Rails by default uses them with the integer sequential id type, so as UUID is non-sequential it generates a random Hash like this 123e4567-e89b-12d3-a456-426614174000 as it doesn't have a sequence Rails can't figure out how to sort the data, then I researched a little bit more to see if there is any other solution and I found that we can use self.implicit_order_column = "created_at" in the Model, with this, those methods work ok it sorts depending on the DateTime created and I was happy. Not for a long time, when another problem came up! When I used seeds to fill a bulk of fake data into the database, all the data had the same DateTime and the sorting failed again, it was the same issue as the initial one. I've decided to look for another alternative and I found ULID, using this I had everything I've needed the sorting works as expected, it isn't predictable and the store in memory is pretty good. I'm still using it and I don't have any issues.

How to implement ULID in Rails?

There is already a gem for ruby add it to your Gemfile

#Gemfile
...
  gem 'ulid'
end

Then run bundle install to install it. Then update your migration or if you are creating a new one should look like this.

# migration
class CreateUsers < ActiveRecord::Migration[6.0]
  def change
   # id: false, to not use id int as default
   create_table :users, id: false do |t|
     # here we create our id
     t.binary :id, limit: 16, primary_key: true

     t.string :given_name
     t.string :family_name
     t.string :email, unique: true, index: true
     t.string :username, unique: true, index: true
     t.string :password_digest
     ...
     t.timestamps
   end
  end
end

First, we disable the autogenerated id by putting id: false and create our own id t.binary :id, limit: 16, primary_key: true what we need to do is fill the id before create, we can do it on each Model but my approach was to create a concern to just include it in the application_record.rb file so it will apply for all the models.

# app/models/concenrs/ulid_pk.rb
require 'ulid'

module UlidPk
  extend ActiveSupport::Concern

  included do
    before_create :set_ulid
  end

  def set_ulid
    self.id = ULID.generate
  end
end

Then in the application_record.rb include it.

# app/models/concenrs/ulid_pk.rb
class ApplicationRecord < ActiveRecord::Base
  include UlidPk
  self.abstract_class = true
end

That's it, now it will autogenerate the id before create.

Note

if you need to create an association you should put the type on it.

# migration
class CreateEvents < ActiveRecord::Migration[6.0]
  def change
   # id: false, to not use id int as default
   create_table :users, id: false do |t|
     # here we create our id
     t.binary :id, limit: 16, primary_key: true

     t.string :name
     t.string :description
     ...
     # Specify the type: binary
     t.references :user, type: :binary, foreign_key: true, index: true

     t.timestamps
   end
  end
end

Hope this can help you, I'll try to make it more autogenerated when I get the chance to avoid put type: :binary or id: false manually. If you have any question feel free to reach me out. Cheers!

How to Architect Rails Project - Part 2

Renzo Diaz — Sun, 08 Dec 2019 21:15:59 +0000

In the previous article, we've done setting up our Surface module
How to Architect Rails Project - Part 1

In this article, we'll cover the following features:

Module Admin
Layouts
Front-End Scaffolding

So, let's kick off...

For our Admin module, we want to get these routes

'domain.com/admins' # Overview, basic reports, charts
'domain.com/admins/blog' # Articles CRUD
'domain.com/admins/work' # Work CRUD

Let's add them to our routes.

# config/routes.rb
Rails.application.routes.draw do
  ...
  namespace :admins do
    resources :blogs
    resources :works
  end
end

Why admins and not admin in singular? Because this module was thought to have multiple user types, users that only can publish articles and won't have permissions to publish works.

Moving on, we need to create the views for our Admin module according to our routes.

Create these files inside app/views folder

app/views
  ├── admins/blogs
  │   └── index.html.erb
  │   └── show.html.erb
  ├── admins/works
  │   └── index.html.erb
  │   └── show.html.erb
  └── layouts 
      └── admin.html.erb

Let's add our markup to admin.html.erb layout, for now, let's copy the content from application.html.erb. Our layout would look like this...

<!DOCTYPE html>
<html>
  <head>
    <title>Portfolio</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>
    <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
  </head>
  <body>
    <%= render "partials/header" %>
    <%= yield %>
  </body>
</html>

Cool right? We have our Admin layout.

Hold on your horses... We are still using the assets from our Surface module (application), we want to isolate Admin/Surface and make them to not depend on each other, so, let's isolate our Admin assets out of the Surface module.

Create these files under app/assets/stylesheets...

app/assets/stylesheets
  ├── admin/base
  │   └── _base.scss
  │   └── _variables.scss
  ├── admin/components
  │   └── _header.scss
  │   └── _sidebar.scss
  └── admin.scss

So our admin.scss would look like this...

// Base theming
@import "admin/base/variables";
@import "admin/base/base";

// Components
@import "admin/components/header";
@import "admin/components/sidebar";

Next, add this line to our base_controller.rb under controller/admins folder

class Admins::BaseController < ApplicationController
  layout 'admin'
end

We need also to tell rails that we want to use admin.css|admin.js in our initializer, so add the following line to config/initializers/assets.rb

Rails.application.config.assets.precompile += %w( admin.js admin.css )

Now let's change our admin.html.erb layout to use admin.css and remove the current header stylesheet which comes from the Surface module.

<!DOCTYPE html>
<html>
  <head>
    <title>Portfolio</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>
    <%= stylesheet_link_tag 'admin', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
  </head>
  <body>
    <%= yield %>
  </body>
</html>

Well done! now if we run rails s and navigate to http://localhost:3000/admins/blogs we should see a blank page. If we inspect elements in the browser we'll see that our styles are coming from admin and not application anymore.

Alright, Renzo, this is cool but I don't see any component and styles on the page yet. Besides the javascript still comes from the Surface module.

Before deep into the components and styles, let's add an Admin module for our javascript files, this is pretty much the same as what we did with styles.

So, let's create an admin.js file under app/javascript/packs folder and add the following lines...

// app/javascript/packs/admin.js
require("@rails/ujs").start()
require("turbolinks").start()
require("@rails/activestorage").start()

Change <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %> to <%= javascript_pack_tag 'admin', 'data-turbolinks-track': 'reload' %> in our admin.html.erb layout

<!DOCTYPE html>
<html>
  <head>
    <title>Portfolio</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>
    <%= stylesheet_link_tag 'admin', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_pack_tag 'admin', 'data-turbolinks-track': 'reload' %>
  </head>
  <body>
    <%= yield %>
  </body>
</html>

Let's restart our server and see what we got, we should see the same blank page if we navigate to http://localhost:3000/admins/blogs. If we inspect the page we'll see that now our javascript comes from admin.

Now we have our js/css isolated from the Surface module, let's add Bulma to our project and start building our components.

Add Bulma gem to our Gemfile at the bottom

gem "bulma-rails", "~> 0.8.0"

Then run bundle install in the terminal.

In this article we are going to use Bulma in both modules Surface/Admin, just to not make this article too long. Remember that we can also isolate to use Bulma for the Admin and any other framework for our Surface.

Now let's build our layout markup correctly for the Admin module.

<!Doctype html>
<html>
...
  <body>
    <%= render "patials/admin/header" %>
    <div class="columns is-fullheight">
      <div class="column is-2 is-sidebar-menu is-hidden-mobile">
        <%= render "partials/admin/sidebar" %>
      </div>
      <div class="column is-main-content">
        <%= yield %>
      </div>
    </div>
  </body>
</html>

Create a admin folder under app/views/partials add these files...

app/views/partials/admin/_header.html.erb

<nav class="navbar">
  <div class="navbar-brand">
    <a class="navbar-item" href="#">
      Logo
    </a> 
    <div class="navbar-burger burger" data-target="navMenubd-example">
      <span></span>
      <span></span>
      <span></span>
    </div>
  </div>

  <div id="navMenubd-example" class="navbar-menu">
    <div class="navbar-start">
    </div>

    <div class="navbar-end">
      <div class="navbar-item has-dropdown is-hoverable">
        <a class="navbar-link">
          <figure class="avatar image is-32x32">
            <img class="is-rounded" src="https://bulma.io/images/placeholders/32x32.png" alt=""/>
          </figure>
          username
        </a>

        <div class="navbar-dropdown is-right">
          <a class="navbar-item">
            Logout
          </a>
        </div>
      </div>
    </div>
  </div>
</nav>

app/views/partials/admin/_sidebar.html.erb

<aside class="menu">
  <p class="menu-label">
    General
  </p>
  <ul class="menu-list">
    <li><%= link_to 'Overview', admins_blogs_path %></li>
  </ul>
  <p class="menu-label">
    Administration
  </p>
  <ul class="menu-list">
    <li>
      <%= link_to 'My Work', admins_works_path %>
    </li>
    <li><%= link_to 'My Work', admins_blogs_path %></li>
    <li><a>Users</a></li>
  </ul>
</aside>

Add some styles

app/assets/stylesheets/admin/base/_variables.scss

$body-size: 16px !default;

// Responsiveness
// 960, 1152, and 1344 have been chosen because they are divisible by both 12 and 16
$tablet: 769px !default;
// 960px container + 40px;
$desktop: 1000px !default;
// 1152px container + 40;
$widescreen: 1192px !default;
// 1344px container + 40;
$fullhd: 1384px !default;

$white: #fff !default;
$orange: hsl(17, 83%, 57%);
$primary: $orange !default;
$primary-invert: $white !default;

// Link colors
$link: $primary !default;
$link-invert: $white !default;
$navbar-height: 3.25rem;

app/assets/stylesheets/admin/base/_base.scss

body {
    overflow-x: hidden;
}
.columns {
    &.is-fullheight {
        min-height: calc(100vh - ( #{$navbar-height} - .75rem ) );
        max-height: calc(100vh - ( #{$navbar-height} - .75rem ) );
        height: calc(100vh - ( #{$navbar-height} - .75rem ) );
        display: flex;
        flex-direction: row;
        justify-content: stretch;

        .column {
            overflow-y: auto;
        }
    }
}    
.is-main-content {
    background: $grey-lighter;
    padding: 1rem  2.5rem 1rem 2rem;
}

app/assets/stylesheets/admin/components/_sidebar.scss

.is-sidebar-menu {
    padding: 2.5rem;
    background: $grey-dark;
    li {
        a {
            color: $white;
        }
    }
}

app/assets/stylesheets/admin/components/_header.scss

.navbar {
    .navbar-item {
        .avatar {
            margin-right: .65rem;
            .is-rounded {
                max-height: 100%;
            }
        }
    }
}

Alright, if we restart our browser at this point and navigate to http://localhost:3000/admins/blogs our dashboard should look like this.

If you got any error through this setup, feel free to drop me a line dev.renzo.diaz@gmail.com I’ll try to answer all your doubts asap.

In part 1 of this article, I mentioned this part 2 will cover CRUDS and Authentication, and React as well.

We'll, we will cover those points in part3, I don't want to make this article too long and don't mix with Rails back-end stuff.

How to Architect Rails Project - Part 1

Renzo Diaz — Wed, 04 Dec 2019 16:31:57 +0000

When I started to build web applications with ruby on rails, I had a lot of questions that I figured out through the years of using the framework. Now in this article, I’m going to share the base structure to start building a web application.

Depending on the requirements our structure could slightly change, in this scenario, I’m going to build a simple portfolio app with a blog of articles.

Before start building our project, let’s imagine two layers one to administrate the site and the other for public access (front pages). Here is how it should look.

Admin (Dashboard):
Only admin users have access and permissions to post articles, add portfolio jobs, see reports, etc.
There are many ways to build modules, for example using ActiveAdmin gem we can crate the admin module, another way is creating engines, but we are going to set up our dashboard module from scratch.

Surface (front pages):
In this module, we’ll put all the public pages like home, about, portfolio, blog, and contact.
Once we have clear this concept, let’s kick-off creating or project…

rails new portfolio -d postgresql -T

-T = skip testing modules. We’ll focus on test and design in other article

Move under the Portfolio directory and run the following commands to create the database and migrations…

rails db:create
rails db:migrate

Until here, we have a clean project with no custom pages or modules. So, let’s start creating our project architecture.
First, under controllers create 2 folders called (admins, surface). Our tree would look like this.

app/controllers
  ├── admins
  └── surface
  └── application_controller.rb

Create these controllers under admins and surface folders base_controller.rb, blogs_controller.rb, works_controller.rb and pages_controller.rb

app/controllers
  ├── admins # Portfolio blog and work management
  │   └── base_controller.rb
  |   └── blogs_controller.rb
  |   └── works_controller.rb
  └── surface # Public pages
  │   └── pages_controller.rb
  └── application.rb

Let’s add some code to our admin controllers…

# admins/base_controller.rb
class Admins::BaseController < ApplicationController
  # Define what users can access to this module
  # Define what view layout to use 
end

#admins/works_controller.rb
# here we are extending from our Admins::BaseControler
class Admins::WorksController < Admins::BaseController
end

# admins/blogs_controllers
# Inherits from Admins::BaseController
class Admins::BlogsController < Admins::BaseController
end

Let’s add some code to our surface controller…

# surface/pages_controller.rb
class Surface::PagesController < ApplicationController
  #define our pages
  def home
  end

  def about
  end
  def work
  end

  def blog
  end

  def contact
  end
end

Next, we are going to add some routes to our app un config/routes.rb.

Rails.application.draw do
  # Define our root page
  root to: 'surface/pages#home'

  # Frontend pages

  # scope module 'surface' to get this format url `domain.com/about, domain.com/work...` 
  # and not `domain.com/surface/about...`
  scope module: 'surface' do
    get '/about', to: 'pages#about', as: 'surface_about'
    get '/work', to: 'pages#work', as: 'surface_work'
    get '/blog', to: 'pages#blog', as: 'surface_blog'
    get '/contact', to: 'pages#contact', as: 'surface_contact'
  end
end

These routes also can be isolated in files, we’ll isolate these routes in the next article.

Now, we should create our views according to our modules, let’s focus first in our Surface module, so let’s create the following folders and views.

app/views
  ├── surface/pages # Write in each file <h1>Page Name</h1> 
  │   └── home.html.erb     # I.e <h1>Home</h1>
  │   └── about.html.erb    # I.e <h1>About</h1>
  |   └── work.html.erb     # I.e <h1>Work</h1>
  |   └── blog.html.erb     # I.e <h1>Blog</h1>
  |   └── contact.html.erb  # I.e <h1>Contact</h1>
  └── partials   
  │   └── _header.html.erb
  |   └── _footer.html.erb
  └── layouts 
  |   └── application.html.erb

Now let’s edit application.html.erb under the layout folder and add the header and footer partials.

Partials are the components that will be used across the site.

Let’s add some Html links to our _header.html.erb under the partials folder...

<header>
  <h1>Logo</h1>
  <nav>
    <ul>
      <li><%= link_to 'Home', root_path %></li>
      <li><%= link_to 'About', surface_about_path %></li>
      <li><%= link_to 'Work', surface_work_path %></li>
      <li><%= link_to 'Blog', surface_blog_path %></li>
      <li><%= link_to 'Contact', surface_contact_path %></li>
    </ul>
  </nav>
</header>

Next, add the header partial to our layout applicaton.html.erb

<!DOCTYPE html>
<html>
  <head>
    <title>Portfolio</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>
    <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
  </head>
  <body>
    <%= render "partials/header" %>
    <%= yield %>
  </body>
</html>

Alright! we have our surface module working perfectly 💯 if you go tho http://localhost:3000 you will be able to navigate between the pages.

If you got any error through this setup, feel free to drop me a line dev.renzo.diaz@gmail.com I’ll try to answer all your doubts asap.

In the next Part 2, will cover the admin module, authentication users, dashboard layout, CRUDS, and some of the front-end stuff.