mystuff/geo/mapforge/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this port is

An OpenBSD port for mapforge, a self-hosted web GIS application. It is a Ruby on Rails 8.1 app backed by MongoDB and Redis, with MapLibre GL JS on the frontend.

• No upstream releases — the port tracks a git snapshot (GIT_COMMIT + SNAP in Makefile)
• To update to a newer commit: change GIT_COMMIT and SNAP, then run doas make makesum

Build commands

doas make fetch          # download source tarball from GitHub
doas make patch          # extract and apply patches
doas make build          # bundle install + bootsnap precompile
doas make fake           # stage into WRKINST
doas make package        # create the .tgz package
doas make install        # install from package
doas make clean=all      # full clean (use instead of make clean)

Run from /usr/ports/mystuff/geo/mapforge/.

Gem dependency handling

This port has no cargo-style bundler module in OpenBSD ports infrastructure. Two approaches:

Development (network access): do-build calls bundle install which fetches gems from rubygems.org and git. Requires network access during the build phase — acceptable for local development.

Proper offline build: Pre-generate a vendor cache and add it as a distfile:

# After make extract, in WRKDIST:
bundle _4.0.3_ config set --local without "development test"
bundle _4.0.3_ package --all --all-platforms --no-install
tar czf ${DISTDIR}/mapforge-gems-20260322.tar.gz vendor/cache/

Then add DISTFILES += mapforge-gems-${SNAP}.tar.gz to the Makefile, extract it in post-extract into ${WRKSRC}/vendor/cache/, and use bundle install --local in do-build.

Two Gemfile entries use git sources (not rubygems.org):

• gpx from https://github.com/digitaltom/gpx (Ruby 4.0 fork)
• net-pop from https://github.com/ruby/net-pop

These will be fetched by bundler during build. For a fully offline build, vendor them too via bundle package --all.

Ruby version

Tied to Ruby 4.0 (MODRUBY_REV = 4.0). The Gemfile enforces ruby "4.0.0" and the Gemfile.lock was generated with bundler 4.0.3 (built into Ruby 4.0).

Relevant paths once ruby40 is installed:

• ${LOCALBASE}/bin/ruby40
• ${LOCALBASE}/bin/bundle40
• ${LOCALBASE}/bin/gem40

C extension gems

Three gems compile native extensions at bundle install time:

• rgeo — geospatial types; optionally links against GEOS (not required)
• rgeo-proj4 — coordinate projections; links against libproj (devel/proj)
• rszr — image resizing; links against MagickCore-6.Q16, MagickWand-6.Q16 (graphics/ImageMagick)

This makes the package architecture-dependent (no PKG_ARCH=*).

Runtime services

The app needs these running before starting:

• mongod from databases/mongodb/80
• redis-server from databases/redis

Start with rcctl start mongod redis mapforge.

Installation layout

Path	Contents
${PREFIX}/share/mapforge/	Application code + vendored gems
${LOCALSTATEDIR}/mapforge/log/	Rails logs
${LOCALSTATEDIR}/mapforge/storage/	Active Storage uploads
${LOCALSTATEDIR}/mapforge/tmp/	Pids, sockets, cache
${PREFIX}/share/examples/mapforge/mapforge.rc	rc.d startup script template

Copy mapforge.rc to /etc/rc.d/mapforge and enable with rcctl enable mapforge.

Environment variables

Required in production:

• SECRET_KEY_BASE — Rails secret (generate with bundle exec rails secret)
• RAILS_ENV=production

Optional OAuth login:

• GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET
• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
• OSM_CLIENT_ID / OSM_CLIENT_SECRET

PLIST

The PLIST placeholder needs to be replaced after a successful build:

doas make fake
doas make update-plist