Stop rebuilding the boring half of every Rails app.

04  /  How-to

From an empty directory to a working app.

A fresh Rails application on PostgreSQL, with Moduler handling sign-up and sign-in. You need Ruby and Docker installed — everything else is below.

1. 01

   Create the project directory

   Make a directory for the app and install Rails.

   Requires Ruby 3.2+ — installed system-wide or through a version manager such as rbenv, asdf or mise.

   $ mkdir example && cd example
   $ gem install rails

2. 02

   Start PostgreSQL

   Add a docker-compose.yml and bring the database up.

   Requires Docker — install it first if you haven't already.

   # docker-compose.yml
   services:
     postgres:
       image: postgres:18
       environment:
         POSTGRES_USER: postgres
         POSTGRES_PASSWORD:
         POSTGRES_HOST_AUTH_METHOD: "trust"
       ports:
         - "5432:5432"
       volumes:
         - postgres:/var/lib/postgresql
   
   volumes:
     postgres:
   
   $ docker-compose up -d

3. 03

   Generate the Rails application

   $ rails new . --name=Example --database=postgresql \
       --javascript=importmap --css=tailwind

4. 04

   Add the Moduler gem

   # Gemfile
   gem "moduler", github: "tkowalewski/moduler"
   
   $ bundle install

5. 05

   Point the database at Docker

   Add the connection details to the default block, so development and test both use the container.

   # config/database.yml
   default: &default
     adapter: postgresql
     encoding: unicode
     max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
     host: localhost
     port: 5432
     user: postgres
     password:

6. 06

   Create the database and install migrations

   Articles store their images and documents their PDFs with Active Storage, so install its tables alongside Moduler's.

   $ bin/rails db:create
   $ bin/rails active_storage:install
   $ bin/rails moduler:install:migrations
   $ bin/rails db:migrate

7. 07

   Configure Moduler

   The resources listed here get a link in the app and admin sidebars. Start with empty lists and add your own as you build them.

   # config/moduler.yml
   shared:
     resources: []
     administration:
       resources: []

8. 08

   Mount Moduler in your routes

   moduler mounts the engine at the path you give it. Routes in the optional block are drawn inside the engine, next to its own.

   # config/routes.rb
   moduler "/application"
   
   # or, with routes of your own
   moduler "/application" do
     get "/reports", to: "reports#index"
   end

9. 09

   Start the application server

   Runs Rails together with the Tailwind watcher. Open http://localhost:3000/application in your browser and sign up.

   $ bin/dev

10. 10

    Make yourself an administrator

    New users are members. Promote your own account and the admin panel opens at /application/administration. Upload your privacy policy and terms under Documents, and every user accepts them before using the app.

    $ bin/rails runner \
        'Moduler::User.find_by!(email_address: "you@example.com").administrator!'