Skip to content

Module 2 — Setup and your first map

5 lessons · setup, environment, first map · 2–3 hours Get your machine ready, run the dispatch deck starter, and put Australia on the screen.

Before we start

This is the slowest module of the tutorial. Most of it is setup, and most setup chapters feel like setup chapters. There’s a PostgreSQL install, a PostGIS extension, a Rails app to clone, a database to seed, three users to sign in as. None of it is spatial work. It’s the foundation everything else stands on.

Stay with it. Lesson 3 is where the foundation pays off — you’ll add a single Phlex view, render it at a route, and a map of Australia appears on the page. The reward at that moment is real. Lessons 4 and 5 add the small details that make the map look like a finished piece of UI rather than a stub: correct coordinate ordering, navigation controls, scale bar, attribution in the right corners.

By the end of Module 2 you’ll have a working Rails 8 application with PostGIS, the Vera gem live, and a styled, controllable MapLibre map of Australia rendered through a Phlex component. Empty of data so far — but the canvas is up.

The lessons in this module:

  1. Rails 8 with PostGIS — install PostgreSQL and PostGIS, clone the dispatch deck starter, run it, sign in as each role, and walk through the codebase you’ve just been handed.
  2. Adding the gem — what the Vera gem brings to the chassis. The Phlex DSL surface, the Stimulus controllers, the action helpers, the importmap pins. Mental model before code.
  3. Your first map — replace the Lab page’s placeholder with a Phlex component rendering an empty positron-styled MapLibre map of Australia.
  4. Coordinates and the lat/lng convention — MapLibre uses [longitude, latitude]. The Vera gem flips to [latitude, longitude]. Why, and what to watch for when you copy coordinates from elsewhere.
  5. The overlay convention — where the map’s overlays live. Navigation, scale, zoom indicator, and overlay UI each have a conventional corner. Add them to the Lab map and the page starts to feel like a real piece of UI.

Setup

Make sure you have:

  • PostgreSQL 14+ with the postgresql-server-dev-* package available (you’ll need it for the pg gem to compile).
  • PostGIS 3+ as an extension package matching your PostgreSQL version.
  • Ruby 3.3+ with Rails 8 installed (gem install rails if you don’t already have it).
  • Node-free environment. Rails 8 uses importmaps; we don’t need Node for the dispatch deck.
  • A modern browser. MapLibre uses WebGL; any current Chrome, Firefox, Safari, or Edge handles it without a fuss.

Lesson 1 walks through installing PostgreSQL and PostGIS if either is new. If you already have a Rails 8 development environment with PostgreSQL, you can skim Lesson 1 and pick up at the “Cloning the starter” section.

You’ll find the starter as a Git tag (chapter-2-1-start) on the tutorial repository, or as a zip download from the tutorial site. Either way, the starter is the same — a Rails 8 application with the chassis pre-built: top bar, sidebar, role-aware navigation, three seeded users, and a development-mode role switcher in the top-right corner. We don’t construct the chassis in this tutorial; we use it as the foundation for the spatial work we’ll add over the remaining modules.

When you’re ready, head into Lesson 1.