Lesson 1 — Rails 8 with PostGIS

In this lesson you’ll get your machine ready and clone the dispatch deck starter. By the end, you’ll have a running Rails 8 application with PostGIS installed, three seeded user accounts, and the chassis we’ll fill in over the rest of the tutorial. We’ll walk through what’s in the starter so you have a feel for the structure before we start writing spatial code in Lesson 3.

Two things to install

The application needs two things on your machine:

• PostgreSQL 14 or later — the database. Most of the tutorial will run on PostgreSQL 16, which is what we test against.
• PostGIS 3.3 or later — the spatial extension that adds geometry types, spatial functions, and spatial indexes to PostgreSQL.

PostGIS is an extension, not a separate program. You install PostgreSQL the normal way, then install the PostGIS extension package, and then enable it inside any database that needs it. Different databases on the same PostgreSQL server can have or not have PostGIS as you choose.

We won’t use Docker. The tutorial assumes a native install because it’s easier for development — no port-mapping headaches, faster startup, and the install instructions are the same as what you’d write up for a colleague.

Installing on macOS

The shortest path on macOS is Homebrew:

1
2
3

brew install postgresql@16
brew install postgis
brew services start postgresql@16

Homebrew links PostGIS against the most recently installed PostgreSQL formula. If you already have an older PostgreSQL installation that’s running, stop it first or you’ll have two servers competing for port 5432.

Installing on Linux

On Debian or Ubuntu, the official PostgreSQL APT repository has the most current versions. The bundled postgresql-16-postgis-3 package installs both pieces:

1
2

sudo apt install postgresql-16 postgresql-16-postgis-3
sudo systemctl enable --now postgresql

Other distributions have similar packages: postgresql-postgis on Fedora, postgis on Arch. The PostGIS website at postgis.net has a per-distribution installation guide if you need it.

Installing on Windows

Use WSL2 with Ubuntu and follow the Linux instructions above. The native Windows PostgreSQL installer ships with PostGIS as a Stack Builder add-on, but the rest of the tutorial assumes a Unix-style command line, so WSL is the path of least friction.

1

psql --version

1

psql -d postgres -c "SELECT version();"

Verify PostGIS is available

Installing PostGIS makes the extension available. It doesn’t enable it in any specific database; you do that per-database with CREATE EXTENSION postgis. We’ll do that in a moment, but first let’s confirm PostGIS is actually present on the server.

1
2
3
4

psql -d postgres
postgres=# SELECT name, default_version
postgres-# FROM pg_available_extensions
postgres-# WHERE name LIKE 'postgis%';

1
2
3
4
5
6

        name         | default_version
---------------------+-----------------
 postgis             | 3.4.2
 postgis_raster      | 3.4.2
 postgis_topology    | 3.4.2
 postgis_tiger_geocoder | 3.4.2

If PostGIS is in the list, you’re ready. We’ll enable it in the dispatch deck’s database in a moment.

Cloning the starter

The dispatch deck chassis is what you start the tutorial with — a working Rails 8 application with the layout, authentication, seed users, and visual styling already in place. You don’t build the chassis; you build the spatial work that goes inside it.

The starter is available two ways:

As a Git tag on the tutorial repository. This is the canonical way and what we recommend if you have Git installed and an SSH key configured for GitHub:

1
2
3

git clone https://github.com/your-org/vera-dispatch-manager-tutorial vera_dispatch_manager
cd vera_dispatch_manager
git checkout chapter-2-1-start

As a zip download. If you’d rather not use Git, the starter is also available as a zip from the tutorial site. Download it, unzip, and cd into the resulting directory.

Either way, you should now have a directory called vera_dispatch_manager with the Rails app inside it.

1

bin/setup

When bin/setup finishes successfully, you should see a message indicating that the database has been seeded with three users. Now let’s start the development server.

Running the application

1

bin/dev

This is Rails 8’s standard development command. It launches three processes simultaneously: the Rails web server (Puma), the Tailwind CSS watcher that recompiles your styles when files change, and the Solid Queue worker for background jobs. They all run in the same terminal with their output multiplexed.

Open a browser to http://localhost:3000 and you should land on the sign-in page. The brand wordmark sits above a centred card with email and password fields. Below the card, in a development- only “Development sign-in” section, you’ll see three buttons — one for each seeded user.

What’s in the starter

Now that the application is running, let’s walk through what’s actually in the codebase. We don’t need to understand every line — most of what’s here is conventional Rails — but a few specific pieces will matter throughout the tutorial.

The directory structure follows a standard Rails layout:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

vera_dispatch_manager/
├── app/
│   ├── components/         ← Phlex components (the chassis)
│   ├── controllers/
│   │   ├── dev/            ← Development-only controllers
│   │   ├── application_controller.rb
│   │   ├── dashboard_controller.rb
│   │   ├── home_controller.rb
│   │   └── ...             ← Role-aware placeholders
│   ├── javascript/
│   │   └── controllers/    ← Stimulus controllers
│   ├── models/
│   │   └── user.rb         ← The User model with role attribute
│   └── views/
│       ├── dashboard/
│       ├── jobs/
│       ├── layouts/
│       │   └── application.html.erb   ← The chassis layout
│       ├── sessions/
│       │   └── new.html.erb           ← The sign-in card
│       └── ...
├── config/
│   ├── database.yml        ← Configured for PostGIS adapter
│   ├── importmap.rb        ← Includes Vera + MapLibre pins
│   ├── routes.rb           ← App routes + dev role-switch route
│   └── ...
├── db/
│   ├── migrate/
│   └── seeds.rb            ← Three role users
├── Gemfile                 ← Includes vera, phlex-rails, etc.
└── ...

The most important pieces for this tutorial are:

app/components/ — about a dozen Phlex components making up the chassis. The top bar, sidebar, role switcher, role badge, data table, page header, auth card, and so on. We won’t change these often; they’re the visual chrome around the spatial work we’ll add.

app/views/layouts/application.html.erb — the page-level shell. This is what wraps every page with the top bar, sidebar, and chrome. Configures Turbo morph as the default refresh strategy. Loads the MapLibre stylesheet that maps need.

config/database.yml — the database adapter is set to postgis (rather than postgresql). This is what enables ActiveRecord to work with geometry columns transparently. Open it now and you’ll see lines like:

1
2
3

default: &default
  adapter: postgis
  encoding: unicode

The postgis adapter is provided by the activerecord-postgis-adapter gem and is a drop-in replacement for postgresql. It supports all standard PostgreSQL features plus the spatial types.

config/importmap.rb — the JavaScript dependency manifest. Already pinned to MapLibre, Geoman (for drawing), and the Vera gem’s controllers. We’ll talk about Vera’s contribution specifically in Lesson 2.

db/seeds.rb — creates three users: manager@vera.test, dispatcher@vera.test, and field_officer@vera.test. All three share the password password for development convenience. The dev role switcher signs you in as the appropriate seed user.

Verifying PostGIS is enabled in the dispatch database

Earlier we verified PostGIS is available on the server. Let’s confirm it’s actually enabled in the dispatch deck’s database — which bin/setup should have done as part of running migrations.

1

bin/rails dbconsole

1

vera_dispatch_manager_development=# SELECT PostGIS_Version();

1
2
3

            postgis_version
---------------------------------------
 3.4 USE_GEOS=1 USE_PROJ=1 USE_STATS=1

The reason PostGIS shows up automatically in this database is that the activerecord-postgis-adapter gem hooks into Rails’s database tasks: when you run db:create, the adapter installs the PostGIS extension as part of creating the database. You don’t need an explicit enable_extension "postgis" migration to get PostGIS working — the adapter handles it. (You’d usually add an explicit migration anyway, for schema.rb transparency. We’ll discuss this in Module 3 when we add our first geometry column.)

Where this leaves us

You now have:

• PostgreSQL 16 (or your version) installed and running
• PostGIS 3 installed and enabled in the dispatch deck’s development database
• The Rails 8 dispatch deck application cloned and running locally
• Three seed users: manager, dispatcher, field officer
• The dev role switcher working — you can switch between roles and see different views
• A clear sense of what’s in the codebase

What you don’t have yet, and what comes next:

• Any maps. The chassis is map-ready (the MapLibre stylesheet is loaded, the Vera importmap pins are configured) but no page actually renders one yet.
• Any spatial data. There’s a users table from the authentication generator, but no Job, Technician, Depot, or ServiceArea models. We’ll add these progressively.
• Any meaningful interaction beyond signing in and switching roles.

Lesson 2 explains what the Vera gem brings to the chassis — what it does, what it doesn’t do, the API surface, and the relationship to MapLibre. Lesson 3 puts the first map on the screen.

If something on this lesson didn’t work — install errors, the app didn’t start, a seed user didn’t sign in correctly — fix it now before continuing. The rest of the tutorial assumes a working chapter-2-1-end state, and tracking down setup issues mid-chapter is harder than fixing them now.