Document the "whoops" error page

[jim-parry]

Provide an error explanation, instead of just "whoops", if things go wrongs early.

[lonnieezell]

Whoops should only show up in production. If this is to help people out during installation, then we might want to default to a development environment, but that poses a security issue for people that don't remember to switch it, which is why I defaulted to production and a more secure install originally.

[jim-parry]

We have six threads on the forum asking what to do with a "whoops" that tells them nothing. I think we need to adjust the "whoops" or be a lot clearer in the installation section of the user guide what that means and how to figure out what went wrong.

[lonnieezell]

IMHO the Whoops screen should give precisely zero information since it's intended to only show up during production installs - you don't want to give potential attackers any details if possible.

Part of this is because it's new for everyone, and I get that. And kind of expected it. I was going for a "secure by default" setup, which isn't always the user-friendliest.

Beefing up docs is always good, but we also know not everyone reads docs or searches forums :)

The only way I can see around it, then, is to make environment development by default. Which, as I mentioned earlier, has its own issues for users. But I'm ok with that, I think, since CI has always aimed to be simple and streamlined to use and a whoops first thing isn't that.

[jim-parry]

OR ... we add a message to the "whoops" page saying where in the user guide the developer can learn how to find out what went wrong, and create that page if needed. Secure by default seem preferential to not.

[lonnieezell]

We could. The only problem I see there is that you tell any potential attacker exactly what framework and version is being used, making it easier for them to use any known security holes, common bad practices, etc.

[jim-parry]

Hmmm. Saying something in the user guide could have the same effect ... even addressing the problem on the forum. The fact that we have so many threads about it might suggest that we need to draw better attention to the problem in the user guide, and/or post a loud RTFM for such posts.

[jim-parry]

Just did a quick search for "whoops" in the user guide, and it is only mentioned in an unrelated comment on the "static pages" page. I can see a developer puzzled when they try to run their fresh-and-easy-to-use CI app, and get an unhelpful "whoops" page :(

[jim-parry]

I think that installation/troubleshooting is the proper place for this, and take a stab at it if you like.

[fefo-p]

Maybe add an install page (I don't remember well, but think that bonfire used to have it) where, after confirming no errors appear, environment can be switched to production?

[lonnieezell]

Bonfire did have that. But Bonfire was a CMS that actually had things that needed to be installed. :) I imagine being able to write to .env files would be problematic.

[michalsn]

I support the idea of sharing as little information as possible when errors occur in production.

Since the debug toolbar is visible in development mode it's hard to imagine that someone would miss it and deploy application without changing the environment.

I would go towards setting a development environment as default, but... I would also add a user guide page called "Deploying your application" (or something similar) where we could mention about some things (some kind of checklist maybe) that should be done to make sure your application is safe before going "live".

[MGatner]

Two ideas

1. AppStarter, Devstarter, and the framework are three different repos with different config files (at this point). What if we had AppStarter start in production and the others in development, so the ones that already need a bit more setup have better messages?

2. Any project started in development could have the Debug toolbar turned on by default (and even start it open) to make it more obvious that “hey this is not for production!”

[lonnieezell]

Since the debug toolbar is visible in development mode it's hard to imagine that someone would miss it and deploy application without changing the environment.

It's more that if they haven't setup a .env file on that server, or something happens and it gets moved accidentally, deleted, etc, then what do we want the environment to default to? To me it's pretty clear that needs to be production otherwise you suddenly get all kinds of information about the site and who knows how long before someone sees it. They might be in a rush to launch before a meeting, or at the end of the day, etc.

Things like that do happen. Need proof - just remember Facebook's gaff from several years back where their servers got misconfigured and were returning raw PHP files instead of executing them.

[michalsn]

@lonnieezell good point. Maybe we should just stick with the current approach. And try to educate folks to switch to development mode when they see "Whoops" page.

[titounnes]

I have an idea. What if the system detects an ip client? If the ip client is the same as the ip server, the environment that is run is development?

[lonnieezell]

Maybe it would make sense to include a .env file in the repo itself with the environment already set to development? That would take care of both concerns, I think. Not sure how well that plays across platform, though I think it should be fine.

What does everyone think?

[jim-parry]

Providing a .env feels funny, as that file is git ignored and supposed to be update-safe for developer/app settings. Maybe we should just add a paragraph to the installation troubleshooting page.

[lonnieezell]

Doh! @jim-parry you're absolutely correct about it not belonging in the repo. Late night fuzzy thoughts strike again. :)

[MGatner]

You can add a file to the repo but still not have it tracked. I think Jim is right that this "feels funny", but it's also an elegant solution for starting a project in development. Back to my idea (1) before we could provide it in just the DevStarter repo.

[fefo-p]

Don't know if it can actually be done, but what if when CI4 detects it's running in development mode a "watermark" is displayed on every render output?

[lonnieezell]

I'm not opposed to it in the devStarter repo.

I think this is just pointing out an area where the docs are lacking and we need to beef them up. If developers won't read the manual - well it's their own fault at that point. :)