Forem: Kevin Luo

Before Kamal: How to Set Up a VM, Domain, and Dockerfile the Easy Way

Kevin Luo — Sat, 06 Sep 2025 02:23:50 +0000

Introduction

Deploying an application on your own machine is never a simple task. Nonetheless, I found using Kamal to deploy apps on my own VM is pretty easy. It allows me to run multiple apps on a very basic and cheap VM with Docker.

Though I really enjoy what Kamal brings to me, I want to write a tutorial for it. However, while I was writing the article about Kamal, I noticed I was always stuck at some points and thought: how can a beginner know how to rent a VM if they have never done that before?

That's why I want to write this article. There are some preparations for Kamal's deployment which are very trivial and simple, but they could intimidate software newbies. In this article, I'm going to introduce how to do the following three things:

Rent a virtual machine
Buy a domain name
Set up a Dockerfile

These are prerequisites of deployment of Kamal (or even any deployment nowadays). To be honest, these three tasks are "boring" part of web app development. However, we will have a little bit of help from modern AI in each step. I hope that makes them no longer dreadful, and you may even enjoy the process 😎

Rent a Virtual Machine (VM)

Since our goal is to deploy things on your own VM, you have to have a VM first. In fact, you can get a VM on cloud providers' websites easily. You can pick any one from those big cloud providers:

Amazon AWS EC2
Google GCP Compute Engine
Microsoft Azure Virtual Machine
DigitalOcean Droplet
Akamai Cloud Compute

I completely don't understand why their names are so random, but they all mean the same thing---their VM service. There are also many smaller providers. If you want, you can ask AI

What VPS options do I have in my region? (VPS, Virtual Private Server)
What cloud providers can I choose to rent a VM? and you should get a suggestion list.

I eventually chose DigitalOcean Droplet. I live in Toronto, and one of their data centers is here. Although I will only show how to enable and connect to a VM on Digital Ocean, the same workflow can be easily applied to all other cloud providers.

Create a new VM

First, go to DigitalOcean. Sign up an account if you don't have one and then log in. Go to the "Droplets" page and click "Create Droplet". You will see many different settings you can configure for the new VM.

For the OS, if you don't have any clue which to install, I suggest choosing Ubuntu or Debian. For the specification of the machine, since we are just practicing and learning, we chose the minimum option. At this moment in September 2025, I get a machine with

1 CPU
1 GB RAM
25 GB SSD Disk
1TB network transfer It costs only $6/month, which is cheaper than Starbucks coffee ☕.

(A DigitalOcean exclusive feature) A good part of Droplet creation is that you can create a SSH key to log in. You can also choose Password to set a root password and set the SSH key authentication later. Up to you.

After the droplet is created successfully. You should see your new VM appear in the Droplets list.

Copy its IP address and use ssh to connect to it.

ssh root@IP_OF_THE_DROPLET
# or if you use a different ssh key
ssh -i ~/.ssh/you_ssh_private_key root@IP_OF_THE_VM

If it connects successfully, then you're good.

Add ssh-key to log in

(If you already added the ssh-key, you can skip this section.) The step is to add ssh-key to log in the VM. Why don't we just stick to the password? The answer is that it will make the deployment easier in the future, and it's also more secure.

You can ask AI if you really don't have a clue how to do that:

How to generate a ssh-key pair and use it to log into my VM?

However, the workflow should be similar like below:

# generate ssh key pair in ~/.ssh, it will create 
# 1. Private key: ~/.ssh/id_ed25519
# 2. Public key: ~/.ssh/id_ed25519.pub
ssh-keygen -t ed25519 -C "your_email@example.com"

# show the content of the public key, and then copy it
cat ~/.ssh/id_ed25519.pub

# login to your VM with your password
ssh root@IP_OF_THE_VM

# edit ~/.ssh/authorized_keys
# paste the public key's content in this file
vim ~/.ssh/authorized_keys

At this point, you should be able to login the VM directly like below and without entering password

ssh root@IP_OF_THE_VM

Buy a domain

You need a domain name to direct to your VM, so your users can use https://your-domain.com instead of a meaningless IP, like 123.123.0.1. You can get a very cheap domain from any domain name provider.

Again, you can ask AI to give you a list of providers if you want. Especially you want a special Top-level domain (the last part of the domain name, like .com, .net), as far as I know, some top-level domains are only sold on specific sites.

You just need to come up with a good domain name you'd like, and search it on those providers' websites. Below is the example that I tried to search get-food-in-gta, and it gave me a long list of available domain names, each one also has a rent price on it

It is just like online shopping (but for geeks...). Whichever creative domain name you get, you need to configure the DNS A record to point to your VM's IP. (Please note that you MUST use IPv4, since IPv6 is not supported by Kamal yet at the moment when I write this article).

Find the entrance to the DNS management page for the domain name you just bought:

Add a new A record. If there is an existing A record, you can delete it.

After the A record is added, create a CNAME record for www. It usually points to the same place, for example: www.google.com and google.com should be the same.

DNS needs a period of time up to 1 day to be activated. Be patient, you can use ssh to connect to the VM by the domain name to check if the settings are active.

ssh root@your-domain.com

Once you connect to the VM by the command above, the VM is all set.

Set up the Dockerfile

I think this is the most interesting part in this AI era, and why I think AI really boost productivity. In the past: Yes, I knew Docker. Yes, I knew Linux. And I know every detail of my application. However, writing a Dockerfile from scratch isn't a joyful task. Recall how you set up your new computer; writing the Dockerfile is exactly like that process.

The situation has changed now. Since a Dockerfile follows a strict format, which is a very reproducible pattern for LLM. AI can generate a well-structured, well-written, good-practice Dockerfile for you if you provide it with the whole project as the context.

Below, I created a small web app by using Nuxt and tried to use Gemini CLI to create a suitable Dockerfile for it. Again, you can use any AI assisting tools: Claude Code, Copilot, Cursor, etc. I just want to present the idea.

Install Gemini CLI

First, go to https://github.com/google-gemini/gemini-cli and follow the instructions to install Gemini CLI on your machine. Then open your project with your editor. If you happen to use VSCode, you can also install the Gemini CLI Companion extension, which can let Gemini CLI know which files are opened in VSCode.

Open the terminal in VSCode and start Gemini CLI. Although we can start telling the Gemini to generate the juicy Dockerfile for us right away, it will be better if you execute the command /init first. /init will analyze the whole project and create a Gemini.md in your project, which will help Gemini CLI have a basic context of your project.

!gemini cli ext](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/50ow23illxauabsgh5jn.png)

When the next step is just to tell Gemini CLI to generate the Dockerfile, there are infinite options there:

Generate a Dockerfile for this project
Generate a Dockerfile for this Nuxt project
Generate a Dockerfile for this Nuxt project. Use Node 22 Alpine as the base image
... You can be more specific and detailed as you would like.

Okay...I admit I oversimplify this process (especially the Dockerfile part) and make AI seem like black magic. A big project which couples with many services like database, cache, storage, etc., may not be as easy as it is demonstrated above. However, I guarantee it will give you a very nice template as the entry point.

Conclusion

Maintaining Linux servers, DNS records and Dockerfile are all skills that deserve thorough studying and let you master them. AI makes the process faster; however, it doesn't mean that we don't need to learn them anymore. Because the current AI doesn't truly "automate" those things, it can still contain many mistakes in it. It just makes them easier to start with.

On the other hand, these things are just the foundation, the starting point of the goal. Our final goal is to deploy our applications, so I think getting the results by AI first is acceptable.😃

Running Cron Jobs by Kamal with the Whenever Gem (The Simple Way)

Kevin Luo — Wed, 09 Jul 2025 02:25:59 +0000

Introduction

I just started learning and practicing Kamal. While I found it's a joy to finally be able to deploy Docker images on my own machine, there are some challenges. One of the biggest challenges is that it's unreasonably difficult to run cron jobs 🥲 On top of that, I like to use the whenever gem to manage cron jobs, which makes it even harder.

I came across a helpful blog post by Alan Morales, which already solves this issue. However, after some research and experiments, I came up with a simpler version, and I'd like to share it here.

Some terms

We know cron is the program that runs routine jobs—like running a script every 5 minutes. cronjobs just means the jobs that will be run by cron. crontab is the command used to edit the cronjobs. (I guess crontab stands for cron table, but I don't have proof for that 😄)

Official Tutorial

The official tutorial suggests running "cron" jobs as a separate server in Kamal. If you check out the tutorial at https://kamal-deploy.org/docs/configuration/cron/, it gives a very concise (but actually clever) example:

bash -c "(env && cat config/crontab) | crontab - && cron -f"

If you follow this exactly, I bet 99% of the time it won’t work for you. Let’s have a close look at this command:

bash -c: starts a new Bash session to execute the commands.
(env && cat config/crontab): env prints all current environment variables. cat config/crontab outputs the contents of the crontab file, which should have cronjob entries like 0 5 * * * /path/to/script.sh.
| crontab -: pipes the combined output into crontab -, which updates the cron jobs.
cron -f: runs cron in the foreground so the Docker container stays alive.

From this, we know we need:

The cron program installed in the Docker image.
An existing cronjobs file to set up with crontab.
Environment variables (env) at the top of the crontab file because cron doesn’t source profile files like .bashrc or .zshrc. Rails commands need variables like PATH, BUNDLE_PATH, RAILS_ENV, etc.
One more thing: cron is designed to run as the root user. Running it as a non-root user often causes "Permission Denied" errors.

Proposed Method

1. Install `cron` in the Dockerfile

Just like the blog post suggests, you need to have cron installed:

# Install cron
RUN apt-get update -qq && \ 
    apt-get install --no-install-recommends -y cron && \ 
    rm -rf /var/lib/apt/lists /var/cache/apt/archives && \ 
    rm -rf /etc/cron.*/*

2. Modify the cmd

In your deploy.yml, set up the cron server like this:

servers:
  cron:
    hosts:
      - www.xxx.yyy.zzz # your server IP
    cmd: bash -c "bundle exec whenever --update-crontab && (env && crontab -l) | crontab - && cron -f"
    options:
      user: root

Explanation:

bundle exec whenever --update-crontab: updates the crontab using whenever.
(env && crontab -l): prints environment variables and current crontab.
| crontab -: sets the new crontab.
cron -f: runs cron in the foreground.
options.user: root: indicates to use root to run the server

The key part is this single line:

bash -c "bundle exec whenever --update-crontab && (env && crontab -l) | crontab - && cron -f"

3. (Optional) Print cron output to Docker’s stdout

Debugging cron in Docker is hard because you can't see the logs. Here's a simple trick: redirect the cron output to Docker’s stdout. Add this line to the top of your config/schedule.rb:

set :output, { standard: '/proc/1/fd/1', error: '/proc/1/fd/2' }

The mysterious /proc/1/fd/1 and /proc/1/fd/2 point to the Docker container logs. You can then check the cron output with:

kamal app logs -r cron -f

Conclusion

In every stage of my career, I’ve found that running cron jobs on production servers is never easy. Running them in Docker makes it even trickier 😆. I hope this changes in the future, but until then, we just have to figure out our own ways.

References

Limit your function calls with debounce

Kevin Luo — Sun, 13 Apr 2025 17:22:21 +0000

What is debounce?

Debounce is a very interesting and important concept in programming. It triggers a function only once when it is called multiple times in a short period. The most common example is the search input field. Assuming we have an input which triggers a database query whenever the user types anything:

<input type="search" oninput="searchProduct(event)" />

<script>
const searchProduct = (event) => {
  // Simulate a search query
  console.log('Query for:', event.target.value);
};
</script>

When a user wants to search "Avocado", it will be like:

types A -> it queries the database for A
types v -> it queries the database for v
types o -> it queries the database for o
types c -> it queries the database for c
and so on.

It will eventually make seven database queries. This behaviour is inefficient and can overwhelm the server with unnecessary requests.

debounce the calls

What we want is that it makes only one query after the whole word is typed. Let's not beat around the bush and see how a debounced version searchProduct can do that:

<input type="search" oninput="searchProduct(event)" />

<script>
let timer;

const debouncedSearchProduct = (event) => {
  clearTimeout(timer);
  timer = setTimeout(() => {
    // Simulate a search query
    console.log('Query for:', event.target.value);
  }, 500)
};
</script>

It will result in like below, only do the database query for one:

Let me explain what debouncedSearchProduct does:

It delays the database query by 500ms with setTimeout and store the timer's ID into the variable timer
If debouncedSearchProduct is called after, it calls clearTimeout(timer) to cancel the timer and do 1. again.

As a result, it makes the database query only when the user stops typing longer than 500ms. Of course, you can adjust 500ms to more suitable value. As you can see, debouncing is very simple to achieve.

debounce at the beginning

The previous example only considers the last event. What if we want to consider the first event and ignore the rest of the events in a timeframe? We can make a few changes to it:

let debounced = false;

const searchProduct = (event) => {
  if (debounced) { return }

  // Simulate a search query
  console.log('Query for:', event.target.value);

  debounced = true;
  setTimeout(() => {
    debounced = false;
  }, 500)
};

Reuse debounce functionality

We can refactor the debounce function to accept a function and return its debounced version so we can reuse it.

<input type="search" oninput="debouncedSearchProduct(event)" />

<script>
const searchProduct = (event) => {
  // Simulate a search query
  console.log('Query for:', event.target.value);
};

function debounce(callback, delay = 500) {
  let timeoutId;
  return (...args) => {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(() => {
      callback.apply(this, args);
    }, delay);
  };
}

const debouncedSearchProduct = debounce(searchProduct, 500);
</script>

To be honest, we don't need to write our own debounce in practice, unless it's required. For example, we can use debounce method from 3rd-party libraries like lodash

<input type="search" oninput="debouncedSearchProduct(event)" />

<script src="https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js"></script>
<script>
const searchProduct = (event) => {
  // Simulate a search query
  console.log('Query for:', event.target.value);
};

const debouncedSearchProduct = _.debounce(searchProduct, 500);
// If you want the leading timeout
const debouncedSearchProduct = _.debounce(searchProduct, 500, {
  leading: true, 
  trailing: false 
});
</script>

Why it's called debounce?

Why is it called debounce? You will know that if you have programmed on a hardware button. The digital world is simple, and there are only 0 and 1. Assume there's a button on a screen, it only has two states, unclicked(0) and clicked(1).

However, in the analog world, the real world, it is not that simple. For example, When you click a button with your finger, and you hear a "click" sound. The physical button part already vibrates multiple times (at least 20 times a human being can only hear sound bigger than 20Hz) so the sensitive sensor under it may send multiple "clicked" signals. This behaviour is called "bounce" and to remove this effect is called "debounce"

Conclusion

Although I use Javascript for examples in this article, it can be applied on any languages. And it's not only for UI, you can apply this concept to any kind of programs. For example, don't call ChatGPT API for every changes at the backend to explode your token usage.

How to do binary search for Ruby's array by #bsearch

Kevin Luo — Mon, 24 Feb 2025 01:46:23 +0000

We sometimes need to check if a value is included in an array. There are many methods to achieve that, e.g. Array#include?, Array#find, etc. But they use linear search, which time complexity is O(n). If it's a sorted array, we know the binary search can give you O(logn) speed. It would be a shame if you didn't know that Ruby's Array can perform binary search out of the box by Array#bsearch. Unfortunately, it may not be that intuitive to use so many people don't know hot to use it. Let's see some examples first:

If you don't know what happened there, you can continue reading this article to know that 😉

There are two very important things to know when using Array#bsearch. First, it can only be performed on a sorted array. Array#bsearch doesn't sort the array for you (you can call array.sort first if you're not sure). Second, Array#bsearch has two modes. That means it has two different ways to use it. The first mode is called Find-Minimum mode, and the other one is called Find-Any mode. These two modes actually do a very similar thing, but you need to send two completely different blocks to it.

Find-Minimum mode

When using Find-Minimum mode,

The block you send to the #bsearch must return a Boolean value, false or true.
If we apply Array.map with the same block, it should return a series of false values followed by a series of true values.
#bsearch will return the first element which returns true

I believe it is easier to understand when seeing the real examples.

array = [1, 3, 5, 7, 9]
array.bsearch { |x| x >= 5 } # => 5

It returns 5, because 5 is the first element that makes the block { |x| x >= 5 } to return true:

# compute x >= 5 for all elements
# [1,     3,     5,    7,    9 ]
[false, false, true, true, true]

If we use another to another block { |x| x >= 6 }

array.bsearch { |x| x >= 6 } # => 7

It returns 7. Why? Again, it is because 7 is the first element make the block return true


# [1,     3,     5,     7,    9 ]
[false, false, false, true, true]

If I use the block { |x| x >= 10 },

array.bsearch { |x| x >= 10 } # => nil

Because there is no element in the array able to make the block return true, the nil will be returned.

Find-Any mode

When using Find-Any mode,

The block you send to the #bsearch must return a Numeric value
It returns a positive number if an array element is smaller than the values you're searching
It returns a negative number if an array element is greater than the values you're searching
It should return zero, if the element matches what you're searching

Even though the rules above feel much more complex than the Find-Minimum mode, trust me, it's also simple.

array = [1, 3, 5, 7, 9]
array.bsearch { |x| 5 <=> x } # => 5

What is <=>? This <=> is called a 3-way comparison, a.k.a spaceship operator. If we compare a <=> b

if a < b, then the result is -1
if a == b, then the result is 0
if a > b, then the result is 1

If you really want to remember it, I hope the picture below can help you:

Anyway, coming back to our example, let's see the computed results of { |x| 5 <=> x } for each element:

array.map { |x| 5 <=> x }
# [1, 1, 0, -1, -1]

5 makes the block return 0, so 5 is returned. If I try to search 6

array.bsearch { |x| 6 <=> x } # => nil

It returns nil because the computed results of { |x| 6 <=> x } is

array.map { |x| 6 <=> x }
# [1, 1, 1, -1, -1]

and it doesn't have 0 in it.

Find-Any mode is very powerful. We can search for a range instead of a single element. For example,

array = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
array.bsearch do |x|
  if x < 4
    1
  elsif x > 6
    -1
  else
    0
  end
end

because the block's results of the array is:

# [1, 2, 3, 4, 5, 6,  7,  8,  9, 10]
  [1, 1, 1, 0, 0, 0, -1, -1, -1, -1]

4, 5 and 6 make the block return 0, so array.bsearch will return any one of them as a result. That's why it is called Find-Any mode.

Conclusion

If you scroll to the top and check the first screenshot now, I think you can understand it. No matter which mode you use, the most important thing is that the search time is O(logn). If you have a very looooong sorted array to search, and Array.find feels so slow (which uses linear search), try Array#bsearch, you will love it!❤️

[Boost]

Kevin Luo — Sun, 16 Feb 2025 01:57:19 +0000

Some tips for making a ruby gem

Kevin Luo ・ Feb 16

#ruby

Some tips for making a ruby gem

Kevin Luo — Sun, 16 Feb 2025 01:52:09 +0000

I recently built a gem, https://github.com/kevinluo201/fx_rates, which is an API wrapper for a good exchange rate service, https://fxratesapi.com/. Anyway, what that gem does is not the point here. I simply want to share my experience of making a ruby gem.

Use bundler to build a gem

First, I suggest using bundler to build a gem. Of course, you can follow the official guide on RubyGem.org's Make your own gem. However, just like other modern projects, it will be much easier to start from boilerplates. bundler can provide us the ruby gem's boilerplates. Assume the gem you're going to make is called your_gem. You can initiate the gem by:

bundle gem your_gem

You should get a directory like below:

tree
.
├── Gemfile
├── LICENSE.txt
├── README.md
├── Rakefile
├── bin
│   ├── console
│   └── setup
├── lib
│   ├── your_gem
│   │   └── version.rb
│   └── your_gem.rb
├── sig
│   └── your_gem.rbs
├── spec
│   ├── spec_helper.rb
│   └── your_gem_spec.rb
└── your_gem.gemspec

Yours can be different because of different versions of bundler. Besides getting this scaffold, it also has some advantages, like:

You can use bundler to handle the dependencies.
You have predefined Rake tasks to test and release the gem
git repository is initiated
etc.

More information can be found at https://bundler.io/guides/creating_gem.html. Now you can start editing the your_gem_name.gemspec to add the basic information for your gem and the dependencies.

Use Zeitwerk

Second, I suggest using zeitwerk gem to manage the constants like classes and modules via organizing the files. I'm going to explain why.

We need to know one thing first: What happens when we require a gem in ruby? For example,

require 'a_gem'

It tells Ruby to execute the entry point ruby file in that a_gem. What is the entry point file in a gem? It is always the file with the same name as your gem's under lib/. In our case, it's lib/your_gem.rb

After we create a gem by bundler, lib/your_gem.rb file should look like this:

# frozen_string_literal: true

require_relative "your_gem/version"

module YourGem
  class Error < StandardError; end
  # Your code goes here...
end

Let's look at require_relative "your_gem/version". It just means it loads lib/your_gem/version.rb. You will realize require 'your_gem only loads the entry file. For other files in the gem, they need to be "required in the entry point file. There's no magic. They won't be loaded or connected automatically.

Now, suppose we want to add a new class, YourGem::Configuration, we can put it under lib/your_gem/configuration.rb.

├── lib
│   ├── your_gem
│   │   ├── configuation.rb
│   │   └── version.rb
│   └── your_gem.rb

The file's content can be an empty class:

# lib/your_gem/configuration.rb
module YourGem
  class Configuration
  end
end

Then we need to require it in the entry point file:
we need to require this new file in the entry point:

# frozen_string_literal: true

require_relative "your_gem/version"
require_relative "your_gem/configuration". # <---- this line

module YourGem
  class Error < StandardError; end
  # Your code goes here...
end

We can get YourGem::Configuration after requiring the entry point file. We can repeat this process for every file in the gem. Although it is very clear, zeitwerk provides another approach to automate this process.

With zeitwek, it can be rewritten as

require "zeitwerk"
loader = Zeitwerk::Loader.for_gem
loader.setup

module YourGem
  class Error < StandardError; end
  # Your code goes here...
end

YourGem::Configuration will be loaded automatically. In fact, all files under lib/your_gem/**/* will be loaded after loader.setup is executed, so you don't need to add any line after adding a new file.

It's a pattern of "convention over configuration", so all your files names have to follow the following pattern:

lib/my_gem.rb         -> MyGem
lib/my_gem/foo.rb     -> MyGem::Foo
lib/my_gem/bar_baz.rb -> MyGem::BarBaz
lib/my_gem/woo/zoo.rb -> MyGem::Woo::Zoo

More details can be found at https://github.com/fxn/zeitwerk

Add configuration

Some gems provide an interface for developers to define global settings, like in rails

Rails.application.configure do
  config.eager_loading = false
  # other settings
end

It looks super cool! We can also let our gem have this ability. Let's say we want to set a global api_key. First, we can create a class to hold the settings. We can use YourGem::Configuration we created above to do that:

module YourGem
  class Configuration
    attr_accessor :api_key

    def initialize
      @api_key = nil
    end
  end
end

Then in the entry_point lib/your_gem.rb, we add a module-level accessor and method:

module YourGem
  class Error < StandardError; end

  class << self
    attr_accessor :config

    def configure
      self.config ||= Configuration.new # <--- YourGem::Configuration has been loaded by zeitwerk above
      yield(config) if block_given?
    end
  end
end

By doing this, we can write and read the api_key by

# write
YourGem.configure do |config| 
  config.api_key = "your-api-key-here"
end

# read
YourGem.config.api_key
# "your-api-key-here"

How to test the gem before releasing it?

Of course, we want to check out how's our gem doing before releasing it. There are 2 ways to test your gem quickly.

bin/console: it opens the irb and loads your gem, so you can
rake install: it is a rake task set up by bundler. It will build a gem package and invode gem install pkg/your_gem to install it in the system. As a result, you can truly test it in your other Ruby projects by require 'your_gem'

How to release it?

All the things we've done for a gem are to release it on https://rubygems.org/. To release the gem, you need an account on https://rubygems.org/ first. So, sign up for one if you haven't done that yet.
Then execute rake build to build a gem file under pkg, it should look like pkg/your_gem-0.0.1.gem. The version number 0.0.1 is defined in the lib/your_gem/version.rb. Finally, we call

gem push pkg/your_gem-0.0.1.gem

and it will push the gem to https://rubygems.org/ 🎉

Conclusion

I think building a gem is not a daily job for most of the developers. However, gems are an essential part of the Ruby community. Why can we always find a gem for our needs? It is because people share what they build. How do we become people who can share? Knowing how to make a gem is the first step. I hope this article can make you feel making a gem is simpler than you thought. 🙏

Drawing Taiwan's Flag with one
and CSS

Kevin Luo — Fri, 22 Nov 2024 03:46:46 +0000

I was impressed very much by @alvaromontoro's work

Drawing Togo's Flag with CSS

Alvaro Montoro ・ Nov 19 '24

#css #html #webdev

of drawing a Togo flag with a single div and bunch of magic CSS. It's truly mind-blowing for me. Therefore, I want to do the same thing. Here is how I've done it.

HTML

I add one <div> with some aria attributes. This will be the single

to render the flag.

<div role="img" aria-label="Flag of Taiwan" class="flag taiwan"></div>

CSS

I used the same method as @alvaromontoro to create a basic background of the Taiwan flag: red background color with a blue rectangle on the top-left.

.flag.taiwan {
  aspect-ratio: 3 / 2;
  height: 500px;
  position: relative;
  background: linear-gradient(rgb(19, 53, 129) 0 0) 0 0 / 50% 50% no-repeat,
    rgb(205, 44, 36);
}

The Sun

Ok, the easiest part is finished. Now it is time for the real deal. The sun on the flag.

It looks pretty complicated, with 12 beams and a circle at the center. How is it possible to use the pseudo elements, ::before and ::after to draw them? It feels like only the clip-path: path() is the only way to do that because path() can draw any shape we want. However, clip-path: path() has a fatal disadvantage: it's not responsive! That means the flag can have only one size if I choose that approach.

I started googling many SVG files of Taiwan flag. And I noticed that they only use 2 elements to represent the sun.

a white 12-beam star
the white circle with a blue border

When the circle is put down on the center of the star. It looks like there are 12 beams surrounding the circle with a desired gap. So smart!. It seems like designers have already figured out this clever way to draw that sun. By taking this approach, I can use ::before as the circle and ::after as the star.

12-beam star

It is very easy to find SVG files of Taiwan flag. Unfortunately, all the stars are drawn by path(). It's because path() is responsive when it is in a real <svg> so they do not have this problem. It is only not responsive in clip-path. The polygon is responsive but I did not find a way to convert path to polygon.

It is a really difficult problem. My final solution is really to calculate all the positions of all the points of the 12-beam star😂 I utilized this fantastic online SVG Path Editorhttps://yqnn.github.io/svg-path-editor/ to visualize all points in the path.

And I asked my dear brother who is very good at math what are the positions of the rest of the points. He used mathematica to solve 12 linear equations and got all the points! 😂

Then, I backed to the path editor to draw the outline of the star as the path and scaled it so it will be in a 100*100 scope.

I then convert all positions to percentages since it's already in 100*100 scope. As a result, we can display the star on the flag

&::after {
    content: '';
    position: absolute;
    top: 6.25%;
    left: 12.5%;
    width: 25%;
    height: calc(3 / 8 * 100%);
    background: white;
    clip-path: polygon(50% 0%,56.6987% 25%,75% 6.6987%,68.3013% 31.6987%,93.3013% 25%,75% 43.3013%,100% 50%,75% 56.6987%,93.3013% 75%,68.3013% 68.3013%,75% 93.3013%,56.6987% 75%,50% 100%,43.3013% 75%,25% 93.3013%,31.6987% 68.3013%,6.6983% 75%,25% 56.6987%,0% 50%,25% 43.3013%,6.6983% 25%,31.6987% 31.6987%,25% 6.6983%,43.3013% 25%);;
  }

The circle

The circle is relatively easier. However, my first attempt was using the border. It failed because the width of the border can only be px. I changed to use radial-gradient. The tricky part is that the percentage in radial-gradient needs to be the diagonal of the element so it also needs some math but it's not that hard.

&::before {
    content: '';
    position: absolute;
    top: 14.375%;
    left: 17.92%;
    width: calc(17 / 120 * 100%);
    height: calc(17 / 80 * 100%);
    background: radial-gradient(circle, white 62.3917%, rgb(19, 53, 129) 62.3917%);
    border-radius: 50%;
    z-index: 2;
  }

Result

The full CSS is

.flag.taiwan {
  aspect-ratio: 3 / 2;
  position: relative;
  background:
    linear-gradient(rgb(19, 53, 129) 0 0) 0 0 / 50% 50% no-repeat,
    rgb(205, 44, 36);

  &::before {
    content: '';
    position: absolute;
    top: 14.375%;
    left: 17.92%;
    width: calc(17 / 120 * 100%);
    height: calc(17 / 80 * 100%);
    background: radial-gradient(circle, white 62.3917%, rgb(19, 53, 129) 62.3917%);
    border-radius: 50%;
    z-index: 2;
  }
  &::after {
    content: '';
    position: absolute;
    top: 6.25%;
    left: 12.5%;
    width: 25%;
    height: calc(3 / 8 * 100%);
    background: white;
    clip-path: polygon(50% 0%,56.6987% 25%,75% 6.6987%,68.3013% 31.6987%,93.3013% 25%,75% 43.3013%,100% 50%,75% 56.6987%,93.3013% 75%,68.3013% 68.3013%,75% 93.3013%,56.6987% 75%,50% 100%,43.3013% 75%,25% 93.3013%,31.6987% 68.3013%,6.6983% 75%,25% 56.6987%,0% 50%,25% 43.3013%,6.6983% 25%,31.6987% 31.6987%,25% 6.6983%,43.3013% 25%);;
  }
}

You can also check out my work on codepen below

Hope you like it!

Use Vue.js SFC in Rails

Kevin Luo — Mon, 11 Nov 2024 01:27:58 +0000

Introduction

Rails Hotwire is good but sometimes you want to build a more reactive. Vue.js is a good choice. In addition, Vue.js SFC is an awesome way to manage your components. However, you cannot just use .vue files because browsers don't recognize .vue files. They need to be compiled into JS codes first.

If you already know Vue.js, you probably know that using vite as the bundler to compile .vue files into JS codes is very common in the Vue.js world. There's a gem vite_rails to integrate vite into rails. I'll introduce how to configure vite_rails so you can use .vue files in Rails.

Preparation

If you want to start it from scratch(optional)

importmap is the default way to manage npm packages after Rails 7. However, we don't want to use importmap now, so add --skip-javascript behind the rails new command to opt out of all Javascript codes.

rails new you_project_name --skip-javascript

Of course, you can keep it if you want. It's just trickier to balance them carefully because they have kind of the same purposes.

Add a simple page

We add a simple index page just for demo

bundle exec rails g controller pages index

it will create the pages_controller an :index action

Install Vite

Add vite_rails in to the Gemfile

gem 'vite_rails'

and run

bundle install
bundle exec vite install

bundle exec vite install will add basic config file and inject some code snippet into the current view template, e.g. in the app/views/layouts/application.html.erb, it will inject these 2 lines

<%= vite_client_tag %>
<%= vite_javascript_tag 'application' %>

vite_client_tag: is for HMR (hot module replacement) so you don't need to refresh the page to the the changes
vite_javascript_tag: it will load entrypoints/application.js

Run vite dev server

The vite dev server will transpile your code in real-time. It's required and also helpful for our development so that we can use features like HMR. Run this command in a new terminal session:

bin/vite dev

Test

To test if the vite_rails is install correctly, you can run rails server by

rails s

and go to http://localhost:3000/pages/index.
Open the console, if you see Vite ⚡️ Rails, then it means you have installed vite_rails successfully!

If you want to run the rails server and vite dev server at the same terminal session. You can install foreman and run foreman start -f Procfile.dev. Procfile.dev was also added by bundle exec vite install

Install Vue

Let's install 2 essential modules:

npm install vue
npm install @vitejs/plugin-vue

vue: It's Vue.js, of course we need it
@vitejs/plugin-vue: this module let vite recognize SFC and transpile .vue into js

To enable @vitejs/plugin-vue, we need to configure vite. Open vite.config.ts and edit it like this:

import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'
import vue from '@vitejs/plugin-vue' // <-------- add this

export default defineConfig({
  plugins: [
    RubyPlugin(),
    vue() // <-------- add this
  ],
})

It's done and we can try to use SFC in our app!

Mount your first Vue component

Let's create our first Vue SFC, App.vue, and mount it!

create App.vue

Create a file app/frontend/components/App.vue and edit it like this:

<template>
  <div>
    <h1>Vue App!</h1>
  </div>
</template>

<script setup>

</script>

<style lang="scss" scoped>
  h1 {
    color: red;
  }
</style>

Note that different versions of vite_rails may have a different path for the source folder. The example here is app/frontend/components/App.vue, but your may be app/javascript/components/App.vue. It depends on where is your entries/appliaction.js

Set the mounting point

Then on our index page's erb, we replace everything with

<%# app/views/pages/index.html.erb %>
<div id="app"></div>

The SFC will be mounted on this div.

import App.vue in application.js

Open app/frontend/entrypoints/application.js. This is the entry point of the javascript program because we wrote <%= vite_javascript_tag 'application' %> in the layout.

import { createApp } from 'vue'
import App from '../App.vue'

const app = createApp(App)
app.mount('#app')

Import the App.vue and mount it

Test

Go to http://localhost:3000/pages/index, you should see the content of our App.vue!

Pass data from Rails to Vue components

Rails is very good at fetching the data in the database. You can make an API endpoint returning JSON string and let the Vue component to call that. However, if you just want the Vue components have the data as props when mounting it. For example, we want the App.vue show the text passed to it as props so we modify it as:

<template>
  <div>
    <h1>{{ msg }}</h1>
  </div>
</template>

<script setup>
defineProps({
  msg: String
})
</script>

<style lang="scss" scoped>
  h1 {
    color: red;
  }
</style>

Now our App.vue is expecting props msg to be sent in.

We set a instance variable in PagesController:

class PagesController < ApplicationController
  def index
    @msg = "Hello Vue on Rails!"
  end
end

We then do a little trick here. Put @msg content on an empty div's data-* attribute, modify app/views/pages/index.html.erb

<%=
  content_tag(
    :div,
    id: 'appProps',
    data: {
      props: {
        msg: @msg
      }
    }.as_json
  ) {}
%>
<div id="app"></div>

it will render the div below on the page.

<div 
      id="appProps" 
      data-props="{&quot;msg&quot;:&quot;Hello Vue on Rails!&quot;}">
</div>

We can then parse the data-props as a JSON in the application.js and sent the JSON to App.vue

import { createApp } from 'vue'
import App from '../components/App.vue'

const appProps = document.getElementById('appProps').dataset.props
const app = createApp(App, JSON.parse(appProps))
app.mount('#app')

(This is a trick used by https://github.com/gazay/gon)

Refresh the page and you can see the App.vue is showing our @msg

Conclusion

Vue.js SFC is a very powerful tool. To be honest, I was attracted to it the first time I saw its syntax. Combining HTML, CSS, JS into a single file is so elegant. Using Vue SFC with Rails is really a joy. Hope you like it!

How to generate self-signed certificates for localhost

Kevin Luo — Wed, 30 Oct 2024 01:18:27 +0000

Introduction

When we develop a website, we usually connect to our development server via HTTP with a special port number like 3000, 5000, or 8888, e.g. http://localhost:3000. Everything works fine and you are happy 😃 One day, you need to connect the dev server via HTTPS. You follow some instructions online but no matter what you've tried, you always get the Not Secure page in Chrome:

Have you run into this situation? In this article, I will show you how to solve this problem to generate valid certificates that can work in Chrome for the local host.

Please aware that the method in this article does not work for Firefox

Generate a certificate for localhost

The solution is to generate a certificate that includes localhost as the domain name and put this information in the certificate's field recognized by modern browsers, so when the browsers check the self-signed certificate and the current URL, it will know it's a valid certificate. It makes sense, right? We will use openssl to generate such a certificate. I use a Macbook, so the example I show here is under macOS

Install openssl

Use Homebrew or other way more suitable for you to install openssl if you don't have openssl installed in your system yet.

brew install openssl
# or
brew upgrade openssl

Generate a certificate by openssl

To generate the certificate we want, execute the command below:

openssl req \
-newkey rsa:2048 \
-x509 \
-nodes \
-keyout localhost.key \
-new \
-out localhost.crt \
-subj /CN='Localhost self-signed certificate' \
-addext "subjectAltName=DNS:localhost" \
-sha256 \
-days 365

You will get

a certificate, localhost.crt
a private key, localhost.key You need these two files to start a HTTPS server. Done!

It's super simple, eh? but it's definitely not straightforward unless you are already familiar with SSL certificates. To be honest, openssl's commands always feel like black magic spells. In the past, I just grabbed pieces from different answers on the internet and tried to do what I want. This time, I do want to understand. Let me (and ChatGPT😆) explain to you what this command actually mean.

openssl req: tell openssl to generate CSR. Although it's the main parameter but it's not important here. I'll explain more below.
-newkey rsa:2048: use RSA to generate private key. If you don't know what's RSA, you only need to know that is the reason we have a private key
-x509: instead of generating a CSR, generate a X.509 certificate. This mysterious X.509 is just the a standard for the certificate used by HTTPS. You can think it like a JSON with specific keys.
-nodes: don't use passphrase to encrypt the private key
-keyout localhost.key: what's the private key's filename. We call it localhost.key here
-new: straightforward, we want a new certificate
-out localhost.crt: we want the output certificate's filename to be localhost.crt
-subj /CN='Localhost self-signed certificate': Set Subject's value. Subject is a field in X.509. CN is Common Name, it can be anything like "My first self-signed certificate"
-addext "subjectAltName=DNS:localhost": We want to add an extension field, Subject Alternative Name, and put DNS:localhost. This is the most important line. Basically, you can ignore all other parameters on this list.
-sha256: use SHA-256 to sign the certificate
-days 365: The validity is 365 days

Trust this certificate in your OS

Because our self-signed certificate is not issued by a trusted CA(Certificate Authority) like GoDaddy, modern browsers will be skeptical and won't trust it. Therefore, we need to make our computer "trust" our own certificate manually:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain localhost.crt

This command registers your new certificate in the system and also trusts it. When your OS trusts it, your browser will trust it accordingly.

Test

We can use the newly generated certificate and private key to run any web server that supports HTTPS. It doesn't matter which web server you want to use. Since Deno2 is the hottest stuff recently and is also super simple, we can use Deno2 to demo.

You can install Deno2 by following their website's instructions, https://deno.com/. After installing Deno2, first we can make an empty folder. Second, we can put the localhost.crt and localhost.key into that folder. Then create a file in the folder, main.ts like below to run a HTTPS web server using the certificate and the private key at port 8000:

// main.ts
Deno.serve({
  port: 8000,
  cert: Deno.readTextFileSync("./localhost.crt"),
  key: Deno.readTextFileSync("./localhost.key"),
}, (_req) => {
  return new Response("Hello, World!");
});

We can run the dev server by executing

deno main.ts

Open Chrome and link to https://localhost:8000, you should see a nice Hello World without any Not Secure warning. Viola!

Generate a certificate for an arbitrary domain

This method can not only be used for localhost. We can also generate a certificate for an arbitrary domain pointing to localhost. Let's say we want to test abc.dev on our machine.

Add the domain in `/etc/hosts`

First, we need to add a new entry in /etc/hosts to make it point to 127.0.0.1, our local:

# executing `sudo vim /etc/hosts` in the terminal
127.0.0.1   abc.dev

Follow the same steps as localhost's example

I hope you get out of vim successfully. Now we only need to do the same things as we did for localhost, the only difference is that we will add abc.dev into subjectAltName

Generate the certificate

openssl req \
-newkey rsa:2048 \
-x509 \
-nodes \
-keyout abc.dev.key \
-new \
-out abc.dev.crt \
-subj /CN='Localhost self-signed certificate' \
-addext "subjectAltName=DNS:localhost,DNS:abc.dev" \
-sha256 \
-days 365

trust the newly generated certificate

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain abc.dev.crt

remember to change the main.ts so it uses abc.dev.crt and .key

Deno.serve({
  port: 8000,
  cert: Deno.readTextFileSync("./abc.dev.crt"),
  key: Deno.readTextFileSync("./abc.dev.key"),
}, (_req) => {
  return new Response("Hello, World!");
});

Test

Voila!

You'll find that https://localhost:8000 also works! It's because we also add DNS:localhost in subjectAltName

How to remove the certificate from the keychain?(MacOS)

We have now learned how to make and trust self-signed certificates. I guess we will have lots of trusted certificates in the system. I guess most of the time, we just want to test some things for development. After we remove the certificates for the testing. We can also remove their records of being trusted from the system. To do that in MacOS, we can open Keychain Access app, find the certificates we trusted and delete them.

MacOS Sequoia removes Keychain Access app from the launch pad, we can still find it at /System/Library/CoreServices/Applications/Keychain Access.app

What is subjectAltName(SAN)?

Here comes a big question: why it works? SAN is just an extra field inside X.509 certificate.To dig deeper, we need to expand the certificate to see what's inside. We can use the command:

openssl x509 -in localhost.crt -text -noout

It will print out the content of the certificate. You can see it's a YAML-like, nested structure:

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            68:5b:f9:5b:72:d2:1f:cd:fd:1b:f9:43:bb:b9:66:cc:53:ab:14:ca
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN=Localhost self-signed certificate
        Validity
            Not Before: Oct 29 03:45:30 2024 GMT
            Not After : Oct 29 03:45:30 2025 GMT
        Subject: CN=Localhost self-signed certificate
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:a6:84:2a:57:5c:c9:a1:69:60:66:6b:43:07:a3:
                    4c:56:68:43:eb:10:29:65:ba:08:d8:75:e8:47:d1:
                    7e:57:16:95:0d:e1:73:3b:69:3f:37:6f:e2:8e:c9:
                    82:74:75:46:e4:16:0f:83:b3:f2:13:77:45:e1:3f:
                    6f:1d:78:36:1b:56:04:65:b8:79:97:c5:15:30:7b:
                    28:59:7a:db:c0:7e:1c:32:f3:03:26:f9:5e:4d:ea:
                    db:76:3d:98:ec:12:ae:6b:10:b6:54:5c:68:88:47:
                    a2:b8:2c:2d:f8:c2:ba:7b:ca:14:a3:a6:e0:ec:49:
                    13:08:ed:bc:67:4f:ef:e7:ab:24:22:65:a8:60:45:
                    74:87:d3:f7:ea:3d:a2:05:e3:46:07:6c:32:2c:48:
                    4d:bd:e0:78:6f:05:dc:7e:8c:b3:4e:1a:e8:c9:0a:
                    cd:3b:2f:cd:9f:2d:a7:7d:4c:76:d8:64:de:7f:9b:
                    06:6c:de:10:cc:44:40:e3:c3:3e:41:85:f0:ca:96:
                    0d:7a:ab:94:26:c9:e3:cb:9a:ca:ab:52:86:c2:28:
                    03:7e:7a:7b:43:29:d2:aa:35:d0:69:1b:37:8f:cb:
                    45:6a:c2:20:37:b3:6e:05:02:43:0b:d5:dd:1d:27:
                    08:51:02:87:85:e3:75:93:03:86:b7:43:8e:b3:15:
                    a0:81
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Key Identifier: 
                2F:90:ED:0C:14:D2:64:11:F8:0C:54:29:EF:EC:55:A7:3B:B1:30:7E
            X509v3 Authority Key Identifier: 
                2F:90:ED:0C:14:D2:64:11:F8:0C:54:29:EF:EC:55:A7:3B:B1:30:7E
            X509v3 Basic Constraints: critical
                CA:TRUE
            X509v3 Subject Alternative Name: 
                DNS:localhost, DNS:abc.dev
    Signature Algorithm: sha256WithRSAEncryption
    Signature Value:
        11:05:1f:f5:80:aa:6d:42:c1:02:9d:a3:3d:c4:0d:29:d3:5b:
        2b:d8:eb:91:7b:56:cf:de:1d:96:76:85:93:91:fa:95:df:86:
        d4:68:a3:6b:3b:dd:92:61:69:dc:05:73:51:5d:f0:2a:7c:a4:
        42:5a:dc:cf:3e:d0:92:19:7a:38:02:b1:20:9d:ce:c8:58:a2:
        3a:45:24:c6:d7:f2:bf:72:5a:bb:cf:49:9e:96:49:02:08:15:
        dd:da:5e:e4:01:40:92:e8:b9:86:7c:da:b7:1b:dc:bc:95:c9:
        6c:38:5c:b7:4c:9d:df:c2:11:49:8e:db:72:41:9f:a6:bd:8e:
        aa:4f:b1:8f:79:c4:ea:eb:03:f1:92:0c:20:3c:f1:d5:8e:9c:
        87:b5:23:66:e9:60:de:10:b9:a6:3b:29:af:f0:bd:22:1f:ec:
        21:c1:10:b9:0b:63:94:9c:c3:2f:87:09:4e:56:0e:24:ae:5d:
        53:54:04:9a:38:10:cb:99:1e:ee:63:47:e3:d3:8b:4b:bd:af:
        f3:76:7f:73:98:fb:71:87:9b:d0:a1:94:d4:4c:7e:04:95:6d:
        83:57:54:93:da:81:44:51:c0:ec:2f:48:24:17:8b:58:65:58:
        08:5c:2b:13:cd:3c:85:b8:2a:2e:06:37:d5:35:90:fb:7f:14:
        da:11:d2:b2

There is a field called Subject and a field called X509v3 Subject Alternative Name

#...
Subject: CN=Localhost self-signed certificate
#...
X509v3 extensions:
      X509v3 Subject Alternative Name: 
        DNS:localhost, DNS:abc.dev

Subject's CN(Common Name) used to be the domain name like CN=abc.dev. However, it can have only one value. It results in that one certificate can only have one domain name bound on it. Therefore, Subject Alternative Name is invented as an extension field to let one certificate support multiple domain names.
The browser used to check only the Subject field in the past, but it somehow it checks only the SAN now. That's why it cannot work if we just look up some instructions online because they often only embed the domain names in the Subject field, and that way has been outdated.

Conclusion

I think the mechanism of HTTPS is complex for many people. That's why it feels hard to understand. Maybe it's not that bad because it's for security. The fewer people understand it the better. However, it will always be a pain in the ass if developers like us do not have a chance to learn about it.
This solution works well for Safari, Chrome or Chromium browsers. However, it does not work for Firefox, which will return MOZILLA_PKIX_ERROR_SELF_SIGNED_CERT warning. To make a self-signed certificate work for Firefox, we may need to create our own CA to sign the certificate. I may write another article showing how to do that one day 😀

Dear AI, can you translate the Rails Guide for me?

Kevin Luo — Sun, 30 Jul 2023 19:59:07 +0000

TL;DR;

I used ChatGPT API to translate the Rails Guide into different languages:

Taiwan's Traditional Chinese🇹🇼 https://ai.rails-guide.com/zh-TW
French🇫🇷 https://ai.rails-guide.com/fr
Lithuanian🇱🇹 https://ai.rails-guide.com/lt
Brazilian Portuguese🇧🇷 https://ai.rails-guide.com/pt-BR
Thai🇹🇭 https://ai.rails-guide.com/th
Simplified Chinese🇨🇳 https://ai.rails-guide.com/zh-CN

Update on 2023/08/12

I added 3 more langauges

Japanese🇯🇵 https://ai.rails-guide.com/jp
Korean🇰🇷 https://ai.rails-guide.com/ko
Espanõl🇪🇸 https://ai.rails-guide.com/es

What's the Rails Guide?

I guess people who read this article already know Rails, however, just in case, I'll briefly introduce Ruby on Rails and the Rails Guide. Feel free to skip this section if you already knew them.

Ruby on Rails is a full-stack web application framework. With Rails, you can build a website that can access your database's data, return as API payload or render them on the user's browser easily and safely. The Rails Guide is the user manual for developers to learn how to use Rails. The Rails Guide is also a crowd-creation and is in the same repository on GitHub. It has very high quality because it is reviewed and modified again and again by numerous seasoned Rails developers. For anyone who wants to learn Ruby on Rails, I will definitely recommend they read the guide first.

Why translate the Rails Guide?

Translating the Rails Guide is not for diversity. The Ruby on Rails guide is written exclusively in English and it is totally fine. However, there are many talented developers all around the world who just cannot read English well. It is really a pity that they don't have a chance to get in touch with this wonderful and powerful web framework, Ruby on Rails, just because it lacks the information in their languages. I believe by translating the Rails Guide, we'll have a better chance for people all over the world to learn Rails.

Why use generative AI to translate Rails Guide?

First of all, generative AI can produce more human text. Moreover, with more context, it can generate more accurate and suitable translations. You must have read some articles which you could tell immediately that were translated by Google Translate because they felt very unnatural.

Second, although there are already many repositories of rails guide in different languages, https://guides.rubyonrails.org/contributing_to_ruby_on_rails.html#translating-rails-guides. However, the problem is that most of them are out of date. Those repositories also depend on volunteers' efforts. The Rails community used to have some enthusiastic fans who were willing to help translate the guide. Unfortunately, since the popularity of Rails plummeted, it hasn't had enough volunteers to continue the work. Using Generative AI to translate documents saves time and human effort. One person can refine the translation result by his/herself easily. It also means that we can update them more frequently. It could be a more sustainable method.

Proposed Workflow

My original plan was simple.

Write a script to read the Rails guide files and send their content to ChatGPT to translate to a specified language.
Then use the existing Rails Guide script to generate HTML files just like the current translation workflow I may wrap the code into a class, AiTranslator, so it should be like this

However, it was not as simple as I imagined 😅

Challenges

There are many challenges in this simple task. I picked some more significant ones here.

Tokens

ChatGPT or other generative AI models can only accept a limited number of tokens. Tokens are composed of both input and output strings. It's not the number of characters or words but only correlated. Tokens are also used for OpenAI to charge your bill.

The current most popular model, gpt-3.5-turbo only allows 4097 tokens for one request. Remember, it's used for both input and output. That means I cannot just upload a whole file to ChatGPT but I need to process a file piece by piece.

Maybe you think: it's easy, you can just send 1 to 2 phrases for a ChatGPT API call, then you'll never exceed the limit.

You're right. However, each ChatGPT request is independent, they don't share any context. I can show you an exmaple of the web page's ChatGPT. If I ask ChatGPT "Do you know NBA?" then ask it "Who's the champion of 2019?
". It will answer it's Toronto Raptors.

However, if I only ask "Who's the champion of 2019?" directly in a new session, ChatGPT will not be able to answer me because of lacking context.

Unlike Google Translate which is like a strengthened dictionary. We'd better treat the Generative AI model like a very smart student. The more input you give it, the better the result it returns to you. As a result, I want to feed ChatGPT text as much as possible so it can have appropriate context to translate the Rails Guide properly.

My approach is like the code block below.



buffer = []
result = ''
File.readlines(file).each do |line|
  if line == "\n" && buffer.join.split.length > @buffer_size
    translated_text = ai_translate(buffer.join)[:text]
    result += translated_text + "\n"
    buffer = []
  else
    buffer << line
  end
end

I declare a buffer = [] at the beginning.
Iterate a file line by line. For each iteration, I'll put one line into buffer
When the number of words exceeds a threshold, I'll send the request to ChatGPT API with the content in the buffer. The threshold, @buffer_size, is defaulted as 700. It's just an empirical magic number
Plus, we know paragraphs in markdown are separated by blank lines, therefore, I also want to translate a whole paragraph in one ChatGPT request.

Prompt phrase

The prompt phrase for the Generative AI model affects the result drastically. I tried a lot of different combinations. And eventually, I made it this way:



LANGUAGES = {
  'zh-TW' => "Traditional Chinese used in Taiwan(台灣繁體中文).",
  'lt' => 'Lithuanian',
  'fr' => 'French',
  'pt-BR' => 'Brazilian Portuguese',
  'th' => 'Thai',
  'zh-CN' => 'Simplified Chinese',
}
system_prompt ||= "Translate the technical document to #{LANGUAGES[@target_language]} without adding any new content."

Translate the technical document: pointing out that we are translating a technical document excerpt so it will know it does not need to translate some elements like code blocks.
LANGUAGES[@target_language]: I don't know whether it is a unique problem for Traditional Chinese. Although they're both Chinese words, the terminologies, writing style and intonation of Traditional Chinese in Taiwan are very different from what Simplified Chinese has. I need to specify it more clearly so I can get the desired result.
without adding any new content.: It is also important to tell ChatGPT not to add extra information because we're translating an article. Otherwise, it will just be like some annoying students in your classroom, who keep talking and add much needless knowledge.

Markdown parsing

The Rails Guide is full of code blocks for showing code examples. It's reasonable not to send a code block separately. I made the line reader a simple state machine. It will change the state to :codeblock when it starts parsing a codeblock and it won't call ChatGPT API until it finishes that block.



state = :readline
buffer = []
result = ''
File.readlines(file).each do |line|
  if line.include?("` ` `") # I need to add spaces between the backtick(`), or Dev.to will have problem
    buffer << line
    state = state == :codeblock ? :readline : :codeblock
  elsif line == "\n" && state == :readline && buffer.join.split.length > buffer_size
    translated_text = ai_translate(buffer.join)[:text]
    result += translated_text + "\n"
    buffer = []
  else
    buffer << line
  end
end

Anchors

When you open any rails guide's page, you can see there's a Chapters block on the right serving as a table of content.

That table is generated automatically by a script. The titles, such as <h1>, <h2>, <h3>, etc. will be assigned id with the title's text. For example, if the title is "Guide Assumption" in the markdown,



### Guide Assumption

it will be rendered as in the final HTML



<h3 id="guide-assumptions">...</h3>

The link in the table of content can then be referred to the elements with that id value.

It works fine in the original Rails Guide. When you click a link in the Chapters, the browser will jump to the corresponding section. However, a problem happens once all titles are translated. After some investigation, I found that it's related to Turbo. I guess it's a Turbo's bug. My current solution is disabling Turbo for the links in the Chapters block.



<ol class="chapters" data-turbo="false">
...
</ol>

Code

Repository: https://github.com/kevinluo201/rails-guide-ai
This repo is forked from the Rails repo so that it can pull the updates of the guide's files. It only has 2 new files:

It only has 2 new files.

guides/rails_guides/ai_translator.rb: it's the main program.
guides/ai_translate.rb: it's the starting point

You can do the following steps if you want to play around with it.

Set a new environment variable call OPENAI_ACCESS_TOKEN and set its value to your personal access token on OpenAI.
add a new language in RailsGuide::AiTranslator, for example, 'jp' => 'Japanese'
Open the terminal, go to guides/ and start translating by executing ```bash

ruby ./ai_translate.rb jp

4. You can also translate a single file, just add a filename after the command
```bash


ruby ./ai_translate.rb jp getting_started.md

After all files are translated, you can just execute the rails existing script to generate HTML, CSS and JS. Unfortunately, it is likely to fail when you do that. Usually, it is because there are duplicated titles which lead to duplicated id in the HTML. You can fix it by finding out which title has the problem and can change that title a bit to avoid the problem. It can also have different problems when translating into different languages. Just try solving them so the process can finish.



bundle exec rake guides:generate:html GUIDES_LANGUAGE=jp

Help Wanted

It is just an experimental project now. There are several issues that can be improved. If you think it is an interesting topic, feel free to discuss it with me.

Current Issues

Anchor links

The table of content is solved by disabling Turbo. However, there are anchor links spread among the articles. They cannot be converted to the correct URL smoothly, especially when it refers to an anchor on another page.

Versioning

The Rails Guide has versions. A version is kind of a snapshot of the guide at a particular time. I haven't thought of a good way to manage them.

Different models

I'm now using gpt-3.5-turbo. I live in Canada so I cannot use Google's Bard. Feel free to change the code to be able to switch different models, like gpt4 or llamas 2

EPUB

Epub files can be generated by the Rails guide script. However, it has errors when I want to import them into the Epub reader software, such as "Books" on OSX. I think it may related to the broken anchor links.

Other stuff

If you have any ideas that can make this project more sustainable, please discuss it with me. For example, it's a guide for Rails, why not build it as a Rails app?

Conclusion

The quality of AI translation is not perfect but acceptable. I'm not concerned about the quality. As far I can see, the limitation of tokens and the trained model are the most significant factors. I believe this problem will be solved by swapping the current model (gpt-3.5-turbo) with a more advanced model in the future. The result shows that this workflow really works and that's the most important lesson for me.

About the cost, I have done many experiments for this idea and I translated the Rails Guides into 6 different languages. It costs me about $27 so each version of the translation costs less than $5 on average. The actual price should be less than that because many experiments just failed.

*Due to its good quality and low cost, Generative AI might be a good solution for technical documents of open-source projects. *

Buy me a coffee

At last, if you like what i'm doing, you can buy me a coffee 😉☕️
](https://www.buymeacoffee.com/kevinluo)

Delve deeply into Devise - Introduce all the Modules

Kevin Luo — Sat, 24 Jun 2023 14:29:55 +0000

Introduction

If you're a Rails developer, I bet you have already heard of or used devise. If you really don't know it, I guess you're reading this article in the far future 😅. devise is a very comprehensive user authentication library for Rails and it's still true in 2023.

devise is very powerful but it's also notorious for being difficult to learn. It has too many features and there isn't a entry point to cut in. Despite that, I'd like to introduce devise starting from its 10 modules. These modules encapsulate 10 common features an authentication system may have. In addition, almost all functionalities of devise are built around these 10 modules. I believe by knowing more about them, it will easier for anyone to harness devise.

In this article, I will enable all 10 modules on the User model one by one. I suggest reading this article sequentially and also following the codes in each chapter. You will build an application with the 100% released devise. If you're totally new to devise or even Rails, you can take a look at my other article to setup a simplest environment and play around with it first.

Setup very basic authentication with Devise in Rails 7

Kevin Luo ・ May 15 '23

#rails #authentication #ruby #tutorial

Devise Modules

Let's have a brief view of all 10 modules.

Database Authenticatable: storing user's password as hash digest and allowing users to sign in
Registerable: allowing new users to register
Confirmable: new users need to click the confirmation link in a confirmation email to activate their accounts.
Validatable: check the username and password validity
Recoverable: "Forgot Password?" feature
Rememberable: the user session will be remembered so the users don't need to log in again after restarting the browser
Timeoutable: the user session will expire after a period of time
Lockable: lock/unlock users
Trackable: track how users use the system, such as how many times a user has signed in
Omniauthable: add Omniauth support

Preparation

Environment

Ruby 3.1.2p20
Rails 7.0.5
devise 4.9.2

Installation

Create a new rails project and install devise. Then execute the command below to initialize devise.



rails generate devise:install

Add Mailer's default_url_options

Many features will send mails out and this is a required configuration.



# config/environments/development.rb
config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }

Add User model

We will use User model for authentication and we want to use the email field as the identifier.

To create the table in the database, execute:



rails g migration create_users email:index

It will create a migration file in db/migrations, please open that file and edit it like below to add some extra constraints like NOT NULL and UNIQUE:



class CreateUsers < ActiveRecord::Migration[7.0]
  def change
    create_table :users do |t|
      t.string :email, null: false
      t.timestamps
    end
    add_index :users, :email, unique: true
  end
end

Run rails db:migrate to make the changes.

Add the User model:



# app/models/user.rb
class User < ApplicationRecord
end

Warning

Please be aware that in practice you should use



rails generate devise User

to create User with a basic devise configuration. However, this article's purpose is to introduce devise's modules and enable them progressively.

Add a root page

Let's add a root page so it can make testing more smooth.

Add a PagesController with an index action ```ruby

app/controllers/pages_controller.rb

class PagesController < ApplicationController
def index
end
end

2. Add the view for `index`
```html


<!-- app/views/pages/index.html.erb -->
<h1>Pages#index</h1>
<% if user_signed_in? %>
  <%= link_to 'Sign out', destroy_user_session_path, data: { turbo_method: :delete }
<% else %>
  <%= link_to 'Sign in', new_user_session_path %>
<% end %>

Modify the <body> of the layout so it can show flash messages ```html

<%= notice %>

<%= alert %>

<%= yield %>


### Routes
Modify the routes like below.
```ruby


# config/routes.rb
Rails.application.routes.draw do
  root "pages#index"
  devise_for :users
end

devise_for :users will generate route paths for devise in the scope of users. It doen't do anything right now because we haven't enabled any module yet. We'll see more examples while introducing each module.

Export Devise views

The last step is to export devise views. This is usually for customization. In fact, we don't have to do this now because we're not going to modify them. It could be helpful to see those pages in code for better understanding.



rails generate devise:views

We have done all the prerequisites. At this point, if you start the rails server and go to http://localhost:3000, it should be a crashed page 😆. There's nothing to concern about. Let's start enabling those modules on User!

Database Authenticatable

The :database_authenticatable module provides 2 main functionalities to the User model:

Store the users' passwords in a hash digest format in the column, encrypted_password.
Verify whether a user's input matches the password digest stored in the database.

It should be a required module. To be honest, I don't know what will happen if you don't include this module but others. Why do you want to do that? If you really need to not include this module, you'd better think twice before using devise.

Enable the module

To enable :database_authenticatable, we need to add one column to the users table, encrypted_password. Execute



rails g migration add_encrypted_password_to_users encrypted_password

It will create a new migration file in db/migrations. Although it's a magic command, it's not magical enough😅 Please open the file and add null: false for the database NOT NULL constraint.



class AddEncryptedPasswordToUsers < ActiveRecord::Migration[7.0]
  def change
    add_column :users, :encrypted_password, :string, null: false
  end
end

Run rails db:migrate to make the changes

We can enable our first module in User by using the devise method:



# app/models/user.rb
class User < ApplicationRecord
  devise :database_authenticatable
end

Usage

Headless usage

:database_authenticatable will introduce a method #password= for setting users password. Open the rails console:



user = User.new(email: 'kevin@taiwan.com')
user.password = '123456'
user.save!

If you check user.encrypted_password, it'll be a gibberish string which is exactly the hash digest of bcrypt so no one knows the true password except you.



user = User.last
user.encrypted_password
# "$2a$12$j.tv091dn9OQPV4seF74Z.PIlohxesFxMGuQh0l39hH4mFS5XyDTi"

We can use the method #valid_password? to verify if a password is correct.



user.valid_password? '123456'
# => true
user.valid_password? 'abcde'
# => false

Testing in browsers

:database_authenticatable module will unlock 3 paths for users to log in and log out. (It really feels like playing a game🎮) You can check them by executing rails routes



    new_user_session GET    /users/sign_in(.:format)  devise/sessions#new
        user_session POST   /users/sign_in(.:format)  devise/sessions#create
destroy_user_session DELETE /users/sign_out(.:format) devise/sessions#destroy

devise/sessions#new is for the sign-in page
devise/sessions#create is create the login session
devise/sessions#destroy is for logging out

Now, you can start the rails server by rails server and go to http://localhost:3000/ on a browser. You'll find the page is fixed now and can display successfully.
Click the Sign In link and you will be led to http://localhost:3000/users/sign_in and you should see a Login page provided by devise
You can then input the user's credentials you just created in the rails console. You should log in successfully and be redirected to the root page.
You can try to click Sign Out and sign out.

Customization

modify settings in config/initializers/devise.rb
modify the exported app/views/devise/sessions/new.html.erb which is for displaying the login page.
execute rails generate devise:controllers users -c sessions to export SessionsController.

Checkpoint - encrypted_password

encrypted_password is a misleading name because it actually uses bcrypt to calculate the hash digest of the password and stores that digest. I didn't check the git log but I guess it's a historical result.

Again, it's okay if you don't understand what the previous paragraph means. I don't think a web developer has to know how the hash algorithm is implemented. However, knowing the difference between an encrypted password and a hashed password is more important. A very easy way to understand them is: you can decrypt an encrypted password to the original password but you cannot revert a hashed digest of a password. As a result, we usually think hashing a password is more secure.

Registerable

The :registerable module is for new users to sign up and manage their data. I think this one is the most confusing one. It sounds like you need to include this module to create users but the fact is that you don't need this module to do that. We just created a new user in the previous chapter, right?

:registerable only adds some extra routing endpoints and makes some views show the links to go to the signup page. Even though we include this module in User, it doesn't add any feature to the model itself.

:registerable can save you some time by preventing you from building a similar workflow again.

Enable the module

Unlike :database_authenticatable, we can just enable :registerable module directly.



# app/models/user.rb
class User < ApplicationRecord
  devise :database_authenticatable, :registerable
end

Usage

After enabling :registerable, a series of user_registration paths will be generated:



cancel_user_registration GET    /users/cancel(.:format)  devise/registrations#cancel
   new_user_registration GET    /users/sign_up(.:format) devise/registrations#new
  edit_user_registration GET    /users/edit(.:format)    devise/registrations#edit
       user_registration PATCH  /users(.:format)         devise/registrations#update
                         PUT    /users(.:format)         devise/registrations#update
                         DELETE /users(.:format)         devise/registrations#destroy
                         POST   /users(.:format)         devise/registrations#create

I think showing examples is easier for you to understand what these paths do.

Create a user

If you go to http://localhost:3000/users/sign_up, you can see a Sign-Up page provided by devise:

You can create a new user if you submit the form with valid input values.

Update or Delete a user

If you logged in, you can go to http://localhost:3000/users/edit to edit your information.

Customization

If you want to customize it:

modify settings in config/initializers/devise.rb
modify the exported views of app/views/devise/registration/*.html.erb
execute rails generate devise:controllers users -c registrations to export RegistrationsController.

Checkpoint - links on pages

If you go to the Log-in page http://localhost:3000/users/sign_in now, you'll find a Sign up link that wasn't there.

It feels like magic. What's happening? This is because the partial, app/views/devise/shared/_links.html.erb checks which modules are enabled and displays the required links. You can check it out to see the details.

Confirmable

I think :confirmable is the second most frequently used module of devise. It provides a very common behaviour: users need to validate their email addresses by clicking a confirmation link sent with a confirmation mail. It can prevent malicious users from signing up with fake emails.

Enable the module

We need to add some required columns on users table for this module.
Execute



rails g migration add_confirmation_to_users confirmation_token:index confirmed_at:datetime confirmation_sent_at:datetime unconfirmed_email

and it should create a migration file like below



class AddConfirmationToUsers < ActiveRecord::Migration[7.0]
  def change
    add_column :users, :confirmation_token, :string
    add_index :users, :confirmation_token, unique: true
    add_column :users, :confirmed_at, :datetime
    add_column :users, :confirmation_sent_at, :datetime
    add_column :users, :unconfirmed_email, :string
  end
end

It will add 4 columns:

confirmation_token: A randomly generated token will be stored in this column and it will be embedded in the confirmation link sent to the user.
confirmation_sent_at: it records the time the confirmation mail was sent
confirmed_at: it records the time after a user clicks the confirmation link and is confirmed. A user has been confirmed if this column is not NULL.
unconfirmed_email: If a user wants to update his/her email address, it will store the new email address.

Run rails db:migrate to make the changes. Then add :confirmable in User to enable the module:



class User < ApplicationRecord
  devise :database_authenticatable, :registerable, :confirmable
end

Usage

Headless

:confirmable adds an array of methods. We're going to try some of them. Open the console:



user = User.first
# check if the user is confirmed
user.confirmed?
# => false

You can call #send_confirmation_instructions



user.send_confirmation_instructions

A confirmation mail with the confirmation link will be sent to the user's email address:



Date: Mon, 19 Jun 2023 12:37:09 -0400
From: please-change-me-at-config-initializers-devise@example.com
Reply-To: please-change-me-at-config-initializers-devise@example.com
To: kevin@taiwan.com
Message-ID: <6490843547bc2_f396c1c90348@F2XWD4WR0C.mail>
Subject: Confirmation instructions
Mime-Version: 1.0
Content-Type: text/html;
 charset=UTF-8
Content-Transfer-Encoding: 7bit

<p>Welcome kevin@taiwan.com!</p>

<p>You can confirm your account email through the link below:</p>

<p><a href="http://localhost:3000/users/confirmation?confirmation_token=uyMSehFApDiMs_-yjcT7">Confirm my account</a></p>

Check the user's attributes now:



user.confirmation_token
# => "uyMSehFApDiMs_-yjcT7"
user.confirmation_sent_at
# => Mon, 19 Jun 2023 16:37:09.185202000 UTC +00:00
user.confirmed_at
# => nil
user.unconfirmed_email
# => nil

user.confirmation_token matches the confirmation_token embedded in the email's confirmation link.
user.confirmation_sent_at was filled
user.confirmed_at is nil because the user hasn't clicked the confirmation link yet
user.unconfirmed_email is nil because we're not doing a reconfirmation

You can confirm the user by calling #confirm:



user.confirm
user.confirmed?
# => true

If you want to do the reconfirmation for the user, you can save the new email in the unconfirmed_email first.



user.email
# => "kevin@taiwan.com"
user.update! unconfirmed_email: 'kevin@taipei.tw'
user.pending_reconfirmation?
# => true
user.send_reconfirmation_instructions
# an email with the reconfirmation link will be sent
user.confirm
user.email
# => 'kevin@taipei.tw'
user.unconfirmed_email
# => nil

Use in browsers

You will not be able to log in as an unconfirmed user. You'll be rejected with a message saying you need to confirm the email first.
If the user wants the system to send the confirmation mail again, they can click "Didn't receive confirmation instruction?" which will lead them to http://localhost:3000/users/confirmation/new to resend the mail.
You can log in as normal after you click the confirmation link in the mail

Customization

You can customize :confirmable by

modify settings in config/initializers/devise.rb
modify the mail template app/views/devise/mailer/confirmation_instructions.html.erb
modify the resend mail page, app/views/devise/confirmations/new.html.erb
run rails generate devise:controllers users -c confirmations to export ConfirmationsController

Validatable

:validatable module provides validations for:

email: check if the input email complies with the email's regex
password: check the length of the input password is 6~128

That's it. It's a very simple module.

Enable the module

:validatable adds model validations for email and password so users needs to have both methods. We've already done that when enabling :database_authenticatable so we can just enable the module in User.



class User < ApplicationRecord
  devise :database_authenticatable, :registerable, :confirmable, :validatable
end

Usage

This is a very straightforward module. Please check the example below:



user = User.new email: 'test-user'
user.password = '1234'
user.save
# => false
user.errors.count
# => 2
user.errors.each { |error| puts error.full_message }
# Email is invalid
# Password is too short (minimum is 6 characters)

Customization

Please forgive me but I personally think it's meaningless to customize this module 😆. Adding validations is way too easy in Rails. For example, the code below can do exactly the same thing as :validatable does.



validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
validates :password, length: { in: 6..128 }

If you want to customize the :validatable, I suggest you just stop using it. Use Rails validation instead and customize it by yourself.

Recoverable

:recoverable is another module that I use frequently in different projects. In a nutshell, it's the "Forget Password?" feature. Users can reset their passwords via a reset link sent to their email addresses.

Enable the module

:recoverable needs some required columns. Execute



rails g migration add_recoverable_to_users reset_password_token:index reset_password_sent_at:datetime

to create a migration file:



class AddRecoverableToUsers < ActiveRecord::Migration[7.0]
  def change
    add_column :users, :reset_password_token, :string
    add_index :users, :reset_password_token, unique: true
    add_column :users, :reset_password_sent_at, :datetime
  end
end

It's pretty similar with :confirmable. When a user wants to reset a password, a randomly generated token will be stored in reset_password_token and it will be embedded in the link in the reset password mail sent to the user's email address. reset_password_sent_at will record the time the mail is sent.

We can enable :recoverable now:



class User < ApplicationRecord
  devise :database_authenticatable, :registerable, :confirmable, :validatable, 
         :recoverable
end

Usage

Headless

You can call #send_reset_password_instructions to create a reset_password_token and it will be embedded in the reset password mail.



user.send_reset_password_instructions
# => 's5ZkHwPHQGAc7DSGCpR_'

Below is a sample of reset password mail. You can find the reset_password_token embedded in the link.



Date: Mon, 19 Jun 2023 21:21:18 -0400
From: please-change-me-at-config-initializers-devise@example.com
Reply-To: please-change-me-at-config-initializers-devise@example.com
To: kevin@taipei.tw
Message-ID: <6490ff0e7179_df83c1c193c8@F2XWD4WR0C.mail>
Subject: Reset password instructions
Mime-Version: 1.0
Content-Type: text/html;
 charset=UTF-8
Content-Transfer-Encoding: 7bit

<p>Hello kevin@taipei.tw!</p>

<p>Someone has requested a link to change your password. You can do this through the link below.</p>

<p><a href="http://localhost:3000/users/password/edit?reset_password_token=s5ZkHwPHQGAc7DSGCpR_">Change my password</a></p>

<p>If you didn't request this, please ignore this email.</p>
<p>Your password won't change until you access the link above and create a new one.</p>

Use in browsers

After enabling :recoverable, you'll get new series of routes endpoints for /passwords



new_user_password  GET    /users/password/new(.:format)  devise/passwords#new
edit_user_password GET    /users/password/edit(.:format) devise/passwords#edit
     user_password PATCH  /users/password(.:format)      devise/passwords#update
                   PUT    /users/password(.:format)      devise/passwords#update
                   POST   /users/password(.:format)      devise/passwords#create

We can open a browser to check what these paths do.

Go to http://localhost:3000/users/sign_in, and you'll find a new link shows up, Forgot your password?
Click that link and you'll be led to http://localhost:3000/users/password/new
If you input a valid email of the users you created in the system and submit the form. A POST request to http://localhost:3000/users/password will be made. Then a reset password mail as described in the previous section will be sent out. You can find that mail in the terminal running rails server. If you have a gem like letter_opener, you can see that mail shown in your browser.
Click or copy-paste the reset password link to open the reset password page http://localhost:3000/users/password/edit?reset_password_token=xxxxxxxxxx
Input a new password and submit the form. A PATCH/PUT request will be made toward http://localhost:3000/users/password. It will then check the reset_password_token and then update the user's password.

Customization

To customize the pages and workflow:

modify settings in config/initializers/devise.rb
Modify the views in app/views/devise/passwords/*.html.erb
Modify app/views/devise/mailer/reset_password_instructions.html.erb for the reset password mail
Execute rails generate devise:controllers users -c passwords to export PasswordsController

Checkpoint - reset password token

If you're a scrupulous person, you might find one interesting thing. I mentioned above that the token will be stored in reset_password_token and will be embedded in the reset password link. However, if you really check their values, you'll find they're different. Take the example we used in this section,

the token embedded in the reset password link is s5ZkHwPHQGAc7DSGCpR_
but if you check user.reset_password_token, it'll be aab3acb2a7dc13e835394c85a14c37417bbd5837692ee67853961bbc6863ee01

Why? How can devise verify the token if they are totally different?

The answer is that the value stored in reset_password_token is also a hash digest, like how devise stores passwords. Furthermore, it will use HMAC-SHA256 hash algorithm to calculate the hash digest. You can run the commands below to check the result.



salt = Devise.token_generator.send(:key_for, :reset_password_token)
OpenSSL::HMAC.hexdigest('SHA256', salt, 's5ZkHwPHQGAc7DSGCpR_')
# => "aab3acb2a7dc13e835394c85a14c37417bbd5837692ee67853961bbc6863ee01"

Why does :database_authenticatable use bcrypt and :recoverable use HMAC-SHA256? The usage is pretty similar. It may be because of the speed, bcrypt is the most secure way to do hashing.

To be frank, the true answer is I don't know. I don't think speed is that critical for resetting passwords. I guess this inconsistency may be common in an open-source project. Different groups of volunteers chose different approaches.

Rememberable

If you've logged in to the system, try restarting your browser. You'll be logged out. It's inconvenient. To solve this issue, :rememberable is introduced. This module provides the ability to keep the user session even if the browser is closed.

How does it do that? Cookies! Generally speaking, :rememberable records the current user's id in a cookie field when a user logs into the system. For instance, if a user with id 10 is logging in, it will record user_id => '10' in the cookie. When the system detects a cookie with user_id => '10', it will assume that the user with id 10 is logged in. How long can it last? It depends on the cookie's expiration time. If the cookie expires after 1 week, then the user's session can be kept for 1 week.

Of course, we don't use a cookie just like that because anyone can modify a cookie's value. You don't want a user to change that user_id to an admin's id and suddenly become an admin. Don't worry. :rememberable also consider how to make it tamperproof and verify the cookie's value.

Enable the module

:recoverable requires one more column. Execute



rails g migration add_rememberable_to_users remember_created_at:datetime

to create a migration file:



class AddRememberableToUsers < ActiveRecord::Migration[7.0]
  def change
    add_column :users, :remember_created_at, :datetime
  end
end

remember_created_at is used for storing the time a user logging with the "Remember me" checkbox checked.

We can enable :rememberable now:



class User < ApplicationRecord
  devise :database_authenticatable, :registerable, :confirmable, :validatable,
         :recoverable, :rememberable
end

Usage

:rememberable utilizes cookies to realize its functionality. Although it does add many methods for the User model, it doesn't make sense if we only call those methods in the rails console. Therefore, I only demonstrate how it works in browsers in this article.

Go to http://localhost:3000/users/sign_in, you'll find there's a new Remember me checkbox
Logging in with the checkbox checked, a parameter rememeber_me will be sent with the form and that will trigger :rememberable mechanism to remember your session in the cookie. ```ruby

"remember_me"=>"1"

3. After logging in, open your browser's devtools (I'm using Chrome) and you can find there a new key, `remember_user_token`, is added to the cookie. It should expire in 2 weeks because that's the default setting. The cookie value seems gibberish. It's actually a **signed message** and it's the **key** of the whole `:rememberable` functionality. It records the currently logged-in user's id and other helpful information. The rails system can take advantage of that information to **remember** the user's session.
  ![Cookie](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/p225dhjvmb5upl3ubc1h.png)
4. With this key-value pair, you can try close and start your browser again. You'll find your session is kept. Nice! 🎉

### Customization
You can change the configuration of `:rememberable` in the initializer, for example, changing the longevity of the cookie to another time. The default is 2 weeks and you can change it to any length you want.
```ruby


# config/initializers/devise.rb
config.remember_for = 1.weeks

Even though there is some stuff devise allows us to customize :rememberable, I don't think it's meaningful to do that. The whole logic of :rememberable is encapsulated well and I can't see the need to change them.

Checkpoint1 - Signed message

For a curious mind like you, I think you must want to know what kind of message is really stored in remember_user_token. First, we copy-paste the gibberish cookie value from our previous example:



eyJfcmFpbHMiOnsibWVzc2FnZSI6Ilcxc3hYU3dpSkRKaEpERXlKRVpWT0VwWVRFOWxPVXh6TG5KRU1qbFBkME5HVFdVaUxDSXhOamczTXpVMU56VXlMakEzTXpBM05TSmQiLCJleHAiOiIyMDIzLTA3LTA1VDEzOjU1OjUyLjA3M1oiLCJwdXIiOiJjb29raWUucmVtZW1iZXJfdXNlcl90b2tlbiJ9fQ==--1c344cce076954bc63f16c7ae6213be0d39ceb6d

Let's demystify it. This message can be split into 2 parts, the true message and the signature, and they're separated by -- in the string. The string before -- is the message itself and the string after -- is the signature. You can try to stop the program by binding.break (this is a functionality from debug gem)



def index
  binding.break
end

The message is not encrypted, it's just encoded by base64 twice so we can decode it easily.



cookie_value = cookies['remember_user_token']
#=> eyJfcmFpbHMiOnsibWVzc2FnZSI6Ilcxc3hYU3dpSkRKaEpERXlKRVpWT0VwWVRFOWxPVXh6TG5KRU1qbFBkME5HVFdVaUxDSXhOamczTXpVMU56VXlMakEzTXpBM05TSmQiLCJleHAiOiIyMDIzLTA3LTA1VDEzOjU1OjUyLjA3M1oiLCJwdXIiOiJjb29raWUucmVtZW1iZXJfdXNlcl90b2tlbiJ9fQ==--1c344cce076954bc63f16c7ae6213be0d39ceb6d
msg, signature = cookie_value.split('--')
rememberable_msg = Base64.decode64(msg)
# => "{\"_rails\":{\"message\":\"W1sxXSwiJDJhJDEyJEZVOEpYTE9lOUxzLnJEMjlPd0NGTWUiLCIxNjg3MzU1NzUyLjA3MzA3NSJd\",\"exp\":\"2023-07-05T13:55:52.073Z\",\"pur\":\"cookie.remember_user_token\"}}"
Base64.decode64(JSON.parse(rememberable_msg)['_rails']['message'])
# => "[[1],\"$2a$12$FU8JXLOe9Ls.rD29OwCFMe\",\"1687355752.073075\"]"

The result



[[1],"$2a$12$FU8JXLOe9Ls.rD29OwCFMe","1687355752.073075"]

is exact the



[user_id, salt_of_password_hash_digest, timestamp]

My user's id was 1 so it recorded 1 in the first element of the message.

In fact, this signed cookie message is a functionality provided by Rails. You can get the value directly by cookies.signed[]. It parses the message correctly and also verifies the signature.



cookies.signed['remember_user_token']
# => [[1], "$2a$12$FU8JXLOe9Ls.rD29OwCFMe", "1687355752.073075"]

The signature is generated based on the message's content. If anyone tries to change the message but doesn't know how to create the corresponding signature, the verification will be failed and it will return nil



cookies['remember_user_token'] = cookies['remember_user_token'][2..-1]
cookies.signed['remember_user_token']
# => nil

Checkpoint2 - SessionCookie

Did you notice there's also another cookie value, _devise_modules_session? That's used for storing the session data. It feels strange. Why do we need another cookie value to remember the session? Isn't the session already kept by that cookie value?

You can check the Expires column and it says _devise_modules_session is a Session Cookie. A session cookie will be destroyed after you close the browser.
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#session_cookie

It's designed to be like this so developers can choose to enable :rememeberable depending on the requirements.

Timeoutable

Users can keep their session forever if they don't close their browsers. That's a problem for some systems. :timeoutable will revoke a user's session if the user doesn't do anything for quite a while. For example, if a user doesn't do anything in the application for 30 minutes, he'll be signed out and redirected to the sign-in page if it's needed.

I felt difficult to imagine how to realize this feature. Surprisingly, it turned out to be simple to do. For every request, devise records the current time in cookies. Therefore, when Rails gets a new request, it can compare the last request's time and the current time to see if the difference is over the threshold. If it's over, then just revoke the user's session.

Enable the module

:timeoutable doesn't need any database migration either because it only uses cookies to realize the feature. Thus, we can enable it directly.



class User < ApplicationRecord
  devise :database_authenticatable, :registerable, :confirmable, :validatable,
         :recoverable, :rememberable, :timeoutable
end

There aren't many things you can customize for this module. The only one may be the timeout time. The default timeout time is 30 minutes. You can change it in the initializer. Later for testing, I'm going to change it to 1 minute.



# config/initializers/devise.rb
# config.timeout_in = 30.minutes
config.timeout_in = 1.minute

Usage

Log into the system in a browser.
You can print session and you should see there's a new key called warden.user.user.session with a nested JSON last_request_at recording a timestamp of the request's time. ```ruby

puts session.to_json
{
# ignore other keys
"warden.user.user.session": {
"last_request_at": 1687446153
}
}

3. Wait for 1 minute and refresh the page, you will be redirected to the root page.

In my opinion, this module conflicts with `:rememberable`, for example, even if the "remember me time" is 2 weeks long, if the "timeout time" is 30 minutes, you'll lose your session after 30 minutes. The only benefit it has when you enable both modules is that **you can keep the session if you restart your browser within the timeout time** but it's not practical 😅.

## Lockable <a name="Lockable"></a>
`:lockable` implements methods for you to lock and unlock users. A locked user cannot log into the system. There are some reasons for you to want to lock users:
- You can lock a user if he/she enters the wrong password several times. It could be a malicious user trying to hack the account
- You want to lock a user because that person already left your organization
- ~~based on your mood~~

### Lockable strategies
`:lockable` has already designed some strategies. You can choose under what kind of situation should you lock or unlock a user. You can configure them in the `config/initializers/devise.rb`

#### Locking strategies
1. `:failed_attempts`: a user will be locked if the wrong password was entered several times
2. `:none`: you have to lock the user manually
The default is `:failed_attempts`

#### Unlocking strategies
1. `:email`: Send an unlock link to the user's email
2. `:time`: A locked user will be unlocked automatically after a certain amount of time
3. `:both`: Enables both strategies
4. `:none`: You have to unlock a user manually
The default is `:both`

### Eanble the module
`:lockable` requires some more columns. Execute

rails g migration add_lockable_to_users failed_attempts:integer unlock_token locked_at:datetime

to create a migration file:
```ruby


class AddLockableToUsers < ActiveRecord::Migration[7.0]
  def change
    add_column :users, :failed_attempts, :integer, default: 0
    add_column :users, :unlock_token, :string
    add_column :users, :locked_at, :datetime
  end
end

locked_at stores the time a user is locked. A user isn't locked when it's NULL.
failed_attempts default value is 0, it will increase 1 whenever a user try to log in with wrong password
unlock_token is a token embedded in the unlock link sent to the user if you allow users to unlock by themself.

We can enable :lockable now:



class User < ApplicationRecord
  devise :database_authenticatable, :registerable, :confirmable, :validatable,
         :recoverable, :rememberable, :lockable
end

Usage

Headless

We can check how to lock a user manually in the rails console.



user = User.first
user.lock_access!
# => 'ZxmxUFVX579zNgpBJftN' This is the unlock_token
user.access_locked?
# => true

When you do that, an unlock mail with a unlock link will be sent to the user's email



Date: Thu, 22 Jun 2023 13:14:42 -0400
From: please-change-me-at-config-initializers-devise@example.com
Reply-To: please-change-me-at-config-initializers-devise@example.com
To: kevin@taipei.tw
Message-ID: <64948182289b0_eb89c1c317fd@F2XWD4WR0C.mail>
Subject: Unlock instructions
Mime-Version: 1.0
Content-Type: text/html;
 charset=UTF-8
Content-Transfer-Encoding: 7bit

<p>Hello kevin@taipei.tw!</p>

<p>Your account has been locked due to an excessive number of unsuccessful sign in attempts.</p>

<p>Click the link below to unlock your account:</p>

<p><a href="http://localhost:3000/users/unlock?unlock_token=ZxmxUFVX579zNgpBJftN">Unlock my account</a></p>

unlock_token will be embedded in the link. By the way, just like :recoverable, the token in the link is the real token and user.unlock_token stores its HMAC digest.

You can unlock the user by



user.unlock_access!
user.access_locked?
# => true
user.locked_at
# => nil
user.unlock_token
# => nil

Use in browsers

:lockable will add 3 more paths:



new_user_unlock GET    /users/unlock/new(.:format) devise/unlocks#new
user_unlock     GET    /users/unlock(.:format)     devise/unlocks#show
                POST   /users/unlock(.:format)     devise/unlocks#create

devise/unlocks#show is for the unlock link
devise/unlocks#new and devise/unlock#create are for asking for resending the unlock mail

We can try entering the password several times to see how this really works. Before the test, let's modify the threshold to 3 times so we don't need to do that too many times.



# config/initializers/devise.rb
config.maximum_attempts = 3

Go to http://localhost:3000/users/sign_in and try to log in with the wrong password for 3 times
Your user account will be locked and you cannot log in even if you enter the correct password.
You can find the unlock link in the unlock mail displayed in your rails server's logs. If you can't find it. You can also click the new link, "Didn't receive unlock instructions?", which leads you to /users/unlock/new to ask for a new unlock mail.
Before you unlock your user account, you can go to the rails console and you'll find user.failed_attempts has increased. ```ruby

user.failed_attempts

=> 4

5. After you click the unlock link, your user will be unlocked. All related columns will be reset
```ruby


user.locked_at
# => nil
user.unlock_token
# => nil
user.failed_attempts
# => 0

Customization

You can customize :lockable by

You can choose lock/unlock strategies and customize other options in config/initializers/devise.rb
modifying the mail template app/views/devise/mailer/unlock_instructions.html.erb
modify the resend instructions page, app/views/devise/unlocks/new.html.erb
run rails generate devise:controllers users -c unlocks to export UnlocksController

Trackable

:trackable provides you the ability to track some information related to the use of devise. I think it'll be very straightforward if you just see the columns required by this module which are also the information that will be tracked. There are 5 of them:

sign_in_count: how many times this user has signed in
current_sign_in_at: the time the current session began
current_sign_in_ip: the IP address of the user when the current session created
last_sign_in_at: the time the last session began
last_sign_in_ip: the IP address of the user when the last session created

You can use that information to detect suspicious actions or see statistics for the use of the system.

Enable the module

We need to add those columns first for :trackable. Execute



rails g migration add_trackable_to_users sign_in_count:integer current_sign_in_at:datetime current_sign_in_ip last_sign_in_at:datetime last_sign_in_ip

and



class AddTrackableToUsers < ActiveRecord::Migration[7.0]
  def change
    add_column :users, :sign_in_count, :integer, default: 0
    add_column :users, :current_sign_in_at, :datetime
    add_column :users, :current_sign_in_ip, :string
    add_column :users, :last_sign_in_at, :datetime
    add_column :users, :last_sign_in_ip, :string
  end
end

After db:migrate, we can enable :trackable:



class User < ApplicationRecord
  devise :database_authenticatable, :registerable, :confirmable, :validatable,
         :recoverable, :rememberable, :timeoutable, :lockable, :trackable
end

Usage

Before opening your browser, open the rails console and check the current information ```ruby

user.sign_in_count

=> 0

user.current_sign_in_at

=> nil

user.current_sign_in_ip

=> nil

user.last_sign_in_at

=> nil

user.last_sign_in_ip

=> nil

2. Open your browser and sign in. Back to the rails console to check the data. You'll find the current_sign_in_x and last_sign_in_x are identical. The IP address is `::1` because you connect to the server locally.
```ruby


user.sign_in_count
#=> 1
user.current_sign_in_at
#=> Thu, 22 Jun 2023 22:02:03.818027000 UTC +00:00
user.current_sign_in_ip
#=> "::1"
user.last_sign_in_at
#=> Thu, 22 Jun 2023 22:02:03.818027000 UTC +00:00
user.last_sign_in_ip
#=> "::1"

If you want to see different IP addresses being recorded, you can use your mobile or other laptops to connect to your development server. You can do that by starting the server with -b argument ```shell

rails s -b 0.0.0.0

4. Sign in on your other devices and then go back to the console to check. `user.sign_in_count` increased by 1 and `current_sign_in_x` information is also updated.
```ruby


user.sign_in_count
#=> 2
user.current_sign_in_at
#=> Thu, 22 Jun 2023 22:06:57.822208000 UTC +00:00
user.current_sign_in_ip
#=> "192.168.1.107"
user.last_sign_in_at
#=> Thu, 22 Jun 2023 22:02:03.818027000 UTC +00:00
user.last_sign_in_ip
#=> "::1"

Checkpoint - IP

How do we know the origin IP address of a request? It's actually a Rails feature provided by Actionpack. It uses ActionDispatch::Request#remote_ip. #remote_ip is smart enough that it will ignore the proxy server's IP addresses and find the original IP address of the request.



request.remote_ip

Omniauthable

:omniauthable is a special module in devise but it's also in charge of a very common feature: letting users log in by using a user's session from another website, e.g. Facebook, Google, Twitter, Github, etc. It's kind of delegating authentication work to those big tech companies. Nowadays, most companies follow OAuth's standards to build the authentication workflow (OAuth always means OAuth 2.0 in this article). However, each company may have different dialects when you communicate via OAuth. This module is called :omniauthable because devise has integrated with the gem omniauth, which provides a unified interface to realize the login process via OAuth.

The root logic of :omniauthable is totally different from traditional authentication, which makes it feel like a social outcast in devise. Therefore, the steps to enable :omniauthable are pretty different. If you aren't familiar with OAuth, don't worry, it's fine to read this chapter. I'll make changes step by step.

I'll use Facebook as the OAuth provider. The main steps we're going to go through are:

[[#Setup the Omniauth environment]]
[[#Connect to Facebook to grant the access]]
[[#Callback from Facebook]]
[[#Use returned user's information to create/find the user and sign him/her in]]

Setup the Omniauth environment

Install assistance gems

Although we know devise has integrated with the gem omniauth, it just defines a unified interface without any functionalities. It will be easier if we just use other gems that implement the customized OAuth workflow for specific providers. For example, I'm going to use Facebook's OAuth login so I add the gems below in the Gemfile and do bundle install:



# Gemfile
gem 'omniauth-facebook', '~> 9.0'
gem 'omniauth-rails_csrf_protection', '~> 1.0.1'

You can find gems for other platforms by googling gems name omniauth-[Provider's name]

Database migration

:omniauthable needs 2 additional string columns:

provider: it stores provider's name, facebook, google,
uid: it stores the user's unique identifier on the provider's website. For instance, you can see it as the id of your Facebook account

Execute



rails g migration AddOmniauthToUsers provider uid:index

and it will produce the migration file like below:



class AddOmniauthToUsers < ActiveRecord::Migration[7.0]
  def change
    add_column :users, :provider, :string
    add_column :users, :uid, :string
    add_index :users, :uid
  end
end

Run rails db:migrate to make the changes.

Enable modules

I assume you already have an App on Facebook for performing OAuth. If you don't know how to create an App on Facebook, you can check out their documentation: https://developers.facebook.com/docs/development/create-an-appso
You can put the corresponding App's ID and App's secret in the devise initializer.



# config/initializers/devise.rb
config.omniauth :facebook, "APP_ID", "APP_SECRET"

Anyway, I think we'd better not commit confidential information in git. I suggest using the Rails credentials to do that. First, edit the credentials YAML:



EDITOR=vim rails credentials:edit

Add credentials:



facebook:
  app_id: "APP_ID"
  app_secret: "APP_SECRET"

We can access the values via Rails.application.credentials in the initializer.



# config/initializers/devise.rb
config.omniauth :facebook, Rails.application.credentials.facebook.app_id, Rails.application.credentials.facebook.app_secret

We can enable the module now. There's a special attribute omniauth_providers to configure, too.



class User < ApplicationRecord
  devise :database_authenticatable, :registerable, :confirmable, :validatable,
         :recoverable, :rememberable, :timeoutable, :lockable, :trackable,
         :omniauthable, omniauth_providers: [:facebook]
end

Connect to Facebook to grant the access

The first step of OAuth is to tell Facebook that you, a Facebook user, agree this web application is going to access your information on Facebook. Let's add the following code:



# config/routes.rb
Rails.application.routes.draw do
  root "pages#index"
  devise_for :users, omniauth_providers: %i[facebook]
end

This will add 2 more routing endpoints:



user_facebook_omniauth_authorize GET|POST /users/auth/facebook(.:format)          devise/omniauth_callbacks#passthru
 user_facebook_omniauth_callback GET|POST /users/auth/facebook/callback(.:format) devise/omniauth_callbacks#facebook

/users/auth/facebook is used to redirect the user to Facebook to grant the access
/users/auth/facebook/callback is used to receive the callback request from Facebook with the asked information. In our case, that should be data including the user's email on Facebook.

Add a link to the /users/auth/facebook which is the user_facebook_omniauth_authorize_path. We use button_to because we want to trigger a form submission to send a POST request. We also add turbo: false to disable Turbo because we'd like to have a full-page reload



<h1>Pages#index</h1>
<% if user_signed_in? %>
  <%= link_to 'Sign out', destroy_user_session_path, data: { turbo_method: :delete } %>
<% else %>
  <%= link_to 'Sign in', new_user_session_path %>
  <%= button_to "Sign in with Facebook", user_facebook_omniauth_authorize_path, data: { turbo: :false } %>
<% end %>

Maybe it's worth mentioning that button_to is a convenient way to create a form with only a submit button. It's almost identical to this:



<%= form_with url: user_facebook_omniauth_authorize_path, data: { turbo: false } do |f| %>
  <%= f.submit "Sign in with Facebook" %>
<% end %>

Callback from Facebook

If you grant access, Facebook will send back the requested information. I didn't mention that but the URL of the path, /users/auth/facebook/callback, was embedded in the previous request. Facebook will redirect the users to that callback URL with the requested information.

If you take a look at rails routes again, you'll find that it's devise/omniauth_callbacks#facebook handling /users/auth/facebook/callback. For other modules, exporting controllers is part of the customization. However, we have to export the OmniauthController for enabling :omniauthable. Execute



rails generate devise:controllers users -c omniauth_callbacks

and make devise use of this exported controller in routes:



# config/routes.rb
Rails.application.routes.draw do
  root "pages#index"
  devise_for :users, omniauth_providers: %i[facebook], controllers: { omniauth_callbacks: 'users/omniauth_callbacks' }
end

You should add the action #facebook in the controller because it doesn't exist yet.



# app/controllers/users/omniauth_callbacks_controller.rb
class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
  def facebook
    # you will get the requested information from Facebook here
  end
end

Use returned user's information to create/find the user and sign him/her in

We now know Facebook will return the requested information, a.k.a the user's data, to Users::OmniauthCallbacksController#facebook so we can use that information to create or find the user in the rails application. How do we do that?

It's where the omniauth gem shines. It defines a shared schema for all providers. You can check it at https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema. omniauth will put all the information in a specific header and you can access that via request.env["omniauth.auth"]. By looking up the schema page, we know this is the data schema



{
  provider: "facebook",
  uid: "uid of user's Facebook account"
  info: {
    email: "user's email"
  }
  // Other fields are ignored
}

The next step is to create or find the user based on that information in #facebook action. We can utilize User.find_or_create_by to do that and then sign in the user by sign_in_and_redirect



class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
  def facebook
    auth = request.env["omniauth.auth"]
    @user = User.find_or_create_by(provider: auth.provider, uid: auth.uid) do |user|
      user.email = auth.info.email
      user.password = Devise.friendly_token[0, 20] # give it a random password
    end
    @user.confirm unless @user.confirmed? # add this line if :confirmable is enabled
    sign_in_and_redirect root_path, event: :authentication # :event is for warden to execute callbacks for :authentication
    set_flash_message(:notice, :success, kind: "Facebook")
  end
end

I usually see people encapsulate the logic of user creation and finding in a class method called .from_omniauth so it can be used by multiple providers in the future.



# app/models/user.rb
def self.from_omniauth(auth)
  find_or_create_by(provider: auth.provider, uid: auth.uid) do |user|
    user.email = auth.info.email
    user.password = Devise.friendly_token[0, 20] # give it a random password
  end
end

so the #facebook can be refactored into



# app/controllers/users/omniauth_callbacks_controller.rb
class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
  def facebook
    @user = User.from_omniauth(request.env["omniauth.auth"])
    @user.confirm unless @user.confirmed? # add this line if :confirmable is enabled
    sign_in_and_redirect @user
    set_flash_message(:notice, :success, kind: "Facebook")
  end
end

Test

Go to the root page, you'll see the new button, Sign in with Facebook
Click the button, and you'll be redirected to Facebook granting access page. My Facebook app name is "develop only" so it says "develop only is requesting access to:"
After granting access, you will find you have already logged in
Open the rails console, you'll find a new user is created and provider and uid are filled ```ruby

user = User.last
user.provider

=> 'facebook'

user.uid.present?

=> true


I only showed the general idea here. You can find more information on `devise`'s wiki page for OmniAuth: https://github.com/heartcombo/devise/wiki/OmniAuth:-Overview. You can read [OAuth RFC](https://datatracker.ietf.org/doc/html/rfc6749) if you are eager to know the details.

## Conclusion
What a journey! We made it 😭! To be honest, I didn't expect I would spend so much time on this article because I've used every module more or less in the past. I thought I was pretty familiar with `devise`. It turned out there are still many things that are different from what I imagined when starting digging deeper. 

I tried to write this article as a tutorial for beginners to enable each module. Therefore, I demonstrate them step by step. In practice, you should execute the macro
```bash


rails generate devise User

and all migrations and related configurations will be there for you (except :omniauthable so I say it's an outcast😆). You can then opt-in to what you want. Whatever, I think it's still valuable if you just took over an existing project that uses devise.

Thank you for reading this article. I hope this article makes you understand more about devise and the authentication of web applications🙏. Maybe after reading this article, you may find you don't need devise at all due to its complexity. If that's true, you can read my other article, building your own authentication system in Rails.

Building a simple authentication in Rails 7 from scratch

Kevin Luo ・ Jun 4 '23

If you think this article is helpful, you can buy me a coffee to encourage me 😉

Code Repo

https://github.com/kevinluo201/devise_modules

References

Set the value of datetime-local input field from an Date object

Kevin Luo — Sun, 11 Jun 2023 17:31:34 +0000

We can use datetime-local to let user enter a date-time string. Most browsers have already implemented a native UI for it. It should be the most ideal way to have date-time input.

<input 
  id="start-time" 
  type="datetime-local" 
  name="start_time"
>

The input is always blank at the beginning. I wanted to give it the current time as its default value but it didn't work.

const currentTime = new Date()
document.getElementById('start-time').value = currentTime // does not work

Because datetime-local only accepts a specific string value, YYYY-mm-ddTHH:MM

YYYY-mm-dd is the year-month-date
T is just the seperator of date and time
HH:MM is the hours and minutes

Therefore, instead of assigning a Date object directly, you have to convert it first into that form. You can use toISOString() because the it will convert the Date object to
YYYY-MM-DDTHH:mm:ss.sssZ and the first part is exactly the same format the datetime-local needs.

const currentTime = new Date()
document.getElementById('start-time').value = currentTime.toISOString().slice(0, 16);

However, it has a problem that it will use the UTC time which is timezone +00:00. I guess not so many people live within that time zone compared to all populations on Earth. I think most developers want to convert that to the local time.

Unfortunately, I found it ridiculously difficult to do that because there's no suitable method for handling that. I think it's due to the fact that most languages have a method similar to strftime so we are used to using an existing method to do what we want. There are some methods like toLocaleString() which seems like we can convert Date into some specific format but none of the format fits our needs. It feels like a basic functionality so I don't want to use any other libraries, either.

Finally, with some help from chatGPT and looking up of MDN page of the Date library. I finally realize the best to do that is to compose the string by myself.

// getFullYear, getMonth, getDate, getHours, getMinutes all return values of local time.
const convertToDateTimeLocalString = (date) => {
  const year = date.getFullYear();
  const month = (date.getMonth() + 1).toString().padStart(2, "0");
  const day = date.getDate().toString().padStart(2, "0");
  const hours = date.getHours().toString().padStart(2, "0");
  const minutes = date.getMinutes().toString().padStart(2, "0");

  return `${year}-${month}-${day}T${hours}:${minutes}`;
}
const currentTime = new Date()
document.getElementById('start-time').value = convertToDateTimeLocalString(currentTime)

Reference

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date

Forem: Kevin Luo

Before Kamal: How to Set Up a VM, Domain, and Dockerfile the Easy Way

Introduction

Rent a Virtual Machine (VM)

Create a new VM

Add ssh-key to log in

Buy a domain

Set up the Dockerfile

Install Gemini CLI

Conclusion

Running Cron Jobs by Kamal with the Whenever Gem (The Simple Way)

Introduction

Some terms

Official Tutorial

Proposed Method

1. Install cron in the Dockerfile

2. Modify the cmd

3. (Optional) Print cron output to Docker’s stdout

Conclusion

References

Limit your function calls with debounce

What is debounce?

debounce the calls

debounce at the beginning

Reuse debounce functionality

Why it's called debounce?

Conclusion

How to do binary search for Ruby's array by #bsearch

Find-Minimum mode

Find-Any mode

Conclusion

[Boost]

Some tips for making a ruby gem

Kevin Luo ・ Feb 16

Some tips for making a ruby gem

Use bundler to build a gem

Use Zeitwerk

Add configuration

How to test the gem before releasing it?

How to release it?

Conclusion

Drawing Taiwan's Flag with one and CSS

Drawing Togo's Flag with CSS

Alvaro Montoro ・ Nov 19 '24

HTML

CSS

The Sun

12-beam star

The circle

Result

Use Vue.js SFC in Rails

Introduction

Preparation

If you want to start it from scratch(optional)

Add a simple page

Install Vite

Run vite dev server

Test

Install Vue

Mount your first Vue component

create App.vue

Set the mounting point

import App.vue in application.js

Test

Pass data from Rails to Vue components

Conclusion

How to generate self-signed certificates for localhost

Introduction

Generate a certificate for localhost

Install openssl

Generate a certificate by openssl

Trust this certificate in your OS

Test

Generate a certificate for an arbitrary domain

Add the domain in /etc/hosts

Follow the same steps as localhost's example

Test

How to remove the certificate from the keychain?(MacOS)

What is subjectAltName(SAN)?

Conclusion

1. Install `cron` in the Dockerfile

Drawing Taiwan's Flag with one
and CSS

Add the domain in `/etc/hosts`