So you want to use Ironman Guide V4
I've been running this stuff since the early builds, and the V4 release is the first version that doesn't require half a dozen workarounds just to function. Before I get into the actual installation steps, I should mention something most people skip: the dependency situation changed between V3 and V4, and if you just blindly run the installer without checking your Python environment first, it will fail silently. I wasted about four hours on that exact thing when V4 first dropped. You can grab the latest version from the official GitHub repository. The URL is right there on their main page under the releases tab. Pick the build that matches your OS — they bundle everything you need in the portable version, which is fine for testing but not ideal for production deployments. The full installer includes the config templates and sample datasets, which saves time later. Once downloaded, run the installer as administrator. Not because of any file permission issues, but because V4 writes registry keys for the scheduler component during installation. If you skip that, the automated backup feature won't trigger on schedule. It will appear to work in the GUI, but nothing will actually back up. I learned that one the hard way when a client reported missing transaction logs and I spent two days tracing why their scheduled jobs were apparently dead.
Configuration basics
The config file lives at C:\Program Files\IronmanGuideV4\config\main.json on Windows, or /etc/ironmanguide/config/main.json on Linux. The default values are reasonable for development environments, but production setups need adjustment. Specifically, the max_workers parameter defaults to 4, which is fine for a single user but becomes a bottleneck once you're processing more than fifty transactions per minute. I bumped mine to 16 on a machine with 32 cores and saw throughput go from roughly 45 TPS to about 310 TPS. That's not linear scaling, obviously — there's overhead in the thread pool management — but it's still a massive improvement over the default. The database connection string follows the standard format. Use postgresql:// for PostgreSQL connections, not postgres://, which the config validator will accept but then fail on at runtime. That inconsistency exists because the underlying ORM library handles both, but the validation regex only catches one. It's a known bug that hasn't been patched yet.
The thing nobody warns you about
The logging system in V4 writes to both a file and stdout simultaneously by default. On systems with heavy I/O or limited disk throughput, this causes noticeable latency in the transaction pipeline. I discovered this when monitoring a deployment on a VM with a slow virtual disk — response times spiked to over two seconds during peak loads, which is completely unacceptable for an Ironman setup. The fix is simple: set the log_output parameter to file_only in the config, and route logs through a log rotation script instead of letting them accumulate on stdout. After switching, response times dropped to around 120ms average on the same hardware. Another edge case worth mentioning: V4's retry logic has a quirk where it treats a 429 Too Many Requests response differently from a 503 Service Unavailable response. The 429 triggers an exponential backoff starting at 1 second, while the 503 immediately retries once and gives up. This means if you're hitting rate-limited endpoints, your retry count will be much lower than you'd expect, and you might think the connection is broken when it's actually just rate limiting. I spent several mornings chasing phantom network issues before realizing the API was throttling us, not dropping packets.
Get the Full Details
Common pitfalls
Memory leaks on long-running instances. The V4 release notes claim they fixed the memory leak from V3, but in practice it's still present under certain conditions. Specifically, if you're using the WebSocket streaming feature with more than 50 concurrent connections, memory usage creeps up by about 50-100MB per hour. It's manageable with regular restarts, but it's there. I set up a cron job to restart the service every 24 hours, and that's been stable for six months now. Backward compatibility is partial. Config files from V3 will load in V4, but some parameters have been renamed or removed. The migration tool is supposed to handle this automatically, but it misses certain custom fields in the advanced section of the config. I recommend manually reviewing your V3 config against the V4 schema before migrating, especially if you've customized the template engine or added third-party plugins. Plugin compatibility. The plugin system in V4 uses a different loading mechanism than V3. Plugins built for V3 won't load unless they're updated to the new API. There's a compatibility layer, but it's marked as deprecated and may be removed in a future release. If you rely on specific plugins, check the plugin authors' repos before upgrading.
When V4 doesn't work
If you're dealing with extremely high-throughput scenarios — I'm talking thousands of transactions per second — V4 isn't the right tool. It's designed for mid-range workloads, and pushing it beyond its intended scope causes data consistency issues. In those cases, you'd be better off looking at dedicated stream processing frameworks. I know because I tried running V4 at 5,000 TPS and ended up with duplicate records and orphaned transactions. Went back to a proper stream processor after that, and the difference was night and day. Similarly, if your environment requires strict ACID compliance across distributed nodes, V4's lightweight transaction model might not be sufficient. It uses a simplified commit protocol that's fast but doesn't guarantee the same level of isolation as a full relational database. For most use cases this is fine, but financial systems and anything handling PII should evaluate this carefully before committing.
Bottom line
Ironman Guide V4 is solid for what it does. The defaults need tweaking for production, the memory behavior under load needs monitoring, and the retry logic has a gap that'll bite you if you don't know it's there. But compared to V3, it's genuinely easier to set up and more stable under normal operating conditions. Just read the changelog, check your config parameters against the new schema, and don't assume the migration tool got everything right.
