Here’s an incomplete list of some problems I’ve experienced in various projects:
-
No comprehensive list of env vars that must be set.
-
The system fails to boot if some remote service is not available.
-
Obtaining the credentials to remote service accounts may require some bureaucracy. In some cases it might not even be possible, depending on the company policy and the availability (or lack) of a staging or per-dev accounts.
-
It’s unclear which other steps need to be done (e.g. generate ssl keys, start other supporting local services) for the system to start and function properly.
-
Conflation of prod-compiled with running on prod machine. E.g. a prod-compiled version should not hardcode the site URL nor the URL of remote services, because it means that I can’t easily run it locally.
These aren’t difficult problems, but once the codebase grows, they are trickier to solve, because there will be a bunch of such small problems scattered around. Furthermore, addressing some of them will require some coordination with other teams (e.g. ops).
As a result, folks will take the path of least resistance, and not try to make it work. Then, when some problems arise which can’t be reproduced on a dev version, folks will try to debug it remotely (e.g. on staging or prod). This works,but it’s much more cumbersome than trying things out locally, and experimenting with potential fixes.
OTOH, if you commit to this goal from the day 1, it should be easier to set things up, because you’re dealing with a smaller codebase, a smaller team, and a smaller set of problems. This property becomes a part of the team culture and philosophy, so it should be much easier to keep it as the team and the codebase grow.
In summary, what I like to see from a project:
-
Starting a prod-compiled version locally should be dead simple. Give me 2-3 commands I need to run, and it should work out of the box, using my local database.
-
The system should work even if there is no network connection. Obviously, the features that depend on external services, such as AWS, can’t work. But e.g. serving local content, interacting with the local db & such should work.
-
It should be clear how to get the credentials to remote services. Ideally, each dev should get their own sandbox account, if possible. If the system depends on other in-house services it should be easy to start these locally.
-
If the prod is containerized, building and starting a local container should also be possible and straightforward.
