a05011396f
Ruby on Rails 8.1 app backed by MongoDB and Redis. Git snapshot from 2026-03-22 (no upstream releases yet). Requires Ruby 4.0, libproj (rgeo-proj4 C ext), and ImageMagick (rszr C ext).
106 lines
3.8 KiB
Markdown
106 lines
3.8 KiB
Markdown
# 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](https://github.com/mapforge-org/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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```sh
|
|
doas make fake
|
|
doas make update-plist
|
|
```
|