Installing the Tool Without Breaking Your Existing Stack
Most people hit a wall within the first twenty minutes. The documentation assumes you already know how your servers talk to each other, which is a generous assumption given how many teams run hybrid setups. I spent three days last October troubleshooting a silent failure where the roadmap API was accepting connections but returning empty payloads, and it turned out to be a certificate authority mismatch between two nodes that nobody had updated since 2022. That kind of thing doesn't show up in any README. Start by checking your environment against the compatibility matrix before you download anything. The official docs list supported operating systems and dependency versions, but they don't always reflect the current build. I keep a running spreadsheet of package versions because the team rotates updates on a six-week cycle and the pinned versions shift without announcement. Python 3.11 is the baseline. Going below that causes import resolution failures in the geocoding module, which then cascades into the property visualization layer failing silently during build time. Node 18 LTS minimum for the frontend components. If you're running Docker, use version 24 or later because the earlier images have a known issue with shared volume mounts that corrupts the cached map tiles on restart. Download the repository from the official source, verify the GPG signature, and only then unpack it. Skip the signature check and you're relying on trust alone. I've seen too many teams skip this step because they're on a deadline. One of my clients deployed an unverified build last quarter and spent two days figuring out why their transaction tracking endpoint was redirecting to a different region entirely. The compromised package was subtle. The redirect looked legitimate in the headers.
Run the dependency installation script, but don't let it complete unchecked. There's a configuration prompt during the first pass that asks about your deployment topology. Select the option matching your actual infrastructure, not the default. The default assumes a single-node deployment with local storage, which is fine for evaluation but will cause permission errors once you try to write to the shared property database. I usually run the install with verbose logging redirected to a file so I can catch these prompts if they get buried. After the install completes, validate the connection to your data sources before opening the UI. Run the health check command from the CLI. It takes about forty-five seconds and tells you whether the backend can reach your MLS feed, your CRM endpoint, and your mapping service. If any of those fail, don't open the application. The dashboard will render anyway, but you'll be working with blank fields and wondering why nothing populates. This step cuts the average debugging time from four hours to roughly twelve minutes. I learned that one the hard way during a demo for a brokerage client who couldn't understand why their lead pipeline looked empty. The CRM token had expired six months prior. Nobody had rotated it. Configure your environment variables in the .env file that gets generated in the project root. Do not store credentials in the config files checked into version control. I know this is obvious to most people reading this, but I've also seen it happen repeatedly. Use a secrets manager or inject them at runtime. The roadmap tool supports HashiCorp Vault and AWS Secrets Manager out of the box. Pick one and stick with it.
When you start the application for the first time, the build will take between eight and fifteen minutes depending on your machine. During this window, the system compiles the mapping assets and builds the localized property index. Do not interrupt it. If you ctrl-C mid-build, the index files end up corrupted and you'll get a fatal error on the next startup that requires a full cache wipe. Wiping the cache means losing your saved view configurations and any custom filters you've set. That's a fifteen-minute reconfiguration problem, not a ten-second restart. There's a configuration option most people miss. In the deployment settings, there's a flag called lazy_property_loading. Set it to true if you're working with datasets over fifty thousand records. When it's false, the app tries to load every property object into memory on startup. On a standard 16GB machine with a large dataset, this causes the process to get killed by the OS before the UI even renders. Setting it to true defers loading until a user actually opens a property detail view. The tradeoff is a one to two second delay when opening individual listings, but that's faster than waiting five minutes for a startup that crashes anyway. The real estate roadmap tool also supports SSO integration, but the documentation on this is incomplete. It works with SAML 2.0 and OIDC, but the attribute mapping for user roles is non-standard. You need to map the group membership field from your identity provider to the internal role key, and the expected format is a pipe-delimited string, not an array. I spent an afternoon writing a transformation middleware because the built-in mapper doesn't handle nested groups. If your organization uses hierarchical AD groups, this is a blocker you need to plan for.
Get the Full Details
The export functionality has a limitation worth noting upfront. The PDF generator caps output at two hundred properties per batch. If you try to export a larger set, the process will hang and eventually return a timeout error. There's no built-in pagination for exports. The workaround is to split your queries by date range or zip code and run multiple export jobs sequentially. It adds ten to fifteen minutes to the overall process for a full-year export, but it actually completes instead of timing out. The team is aware of this limitation and there's an open issue tracking it, but as of the last build, it hasn't been resolved. If you need to customize the map layers, you'll work with the GeoJSON configuration files in the assets directory. Each layer is defined as a separate file, and they're loaded in alphabetical order. If you create custom overlays for your neighborhoods, name them with a prefix that reflects their sort order. This isn't arbitrary. The renderer processes them sequentially and later layers draw on top of earlier ones. I once had a client who named their flood zone overlay "Flood_Zones" and their zoning layer "Zoning_Map", which put the zoning on top and made the flood zones invisible. Renaming them to "01_Flood" and "02_Zoning" fixed it immediately. The documentation mentions layer order matters but doesn't explain how the sorting works. Backup your configuration before any major update. The upgrade process overwrites the settings file but preserves the database. That sounds safe until you realize the new version expects a slightly different schema for custom field definitions. I've restored from backup twice in the last year because someone ran the upgrade without checking the migration notes. The migration notes exist, but they're buried in a changelog that gets updated after the release, not before. Read the pre-release notes on the forum if there's an upcoming version. They're more detailed than the official changelog.
This tool works well for teams that need visual pipeline management across multiple markets. It's not built for high-frequency trading scenarios or real-time data feeds that refresh every few seconds. The refresh interval is configurable but the minimum practical refresh rate is thirty seconds due to how the caching layer is designed. If your workflow depends on second-by-second updates, this isn't the right platform and you should look at something event-driven instead. The architecture just isn't built for that cadence.
