Self-hosted install feedback

[cameronj86]

Got the container up and running after +2 hours troubleshooting and wanted to give some feedback while it's fresh.

General Takeaways

• I think it's great that the docs are detailed/informative to users but I also think new users' initial goal is just to get it up and running, so a shorter, more opinionated install guide might be more helpful. The longer install documentation runs the risk of users (present company included) skimming documentation and missing steps completely.

Documentation-related

• The docker install instructions direct users to the config page. Being that the reference point is setting up the .env & env.laravel files, perhaps they can be explicitly referenced on the config page. In hindsight, I now realize that .env variables are at the top and env.laravelvariables are at the bottom, but in the moment, I was trying to configure .env and hit w/ ~3 pages of definitions which felt overwhelming. Clearer headers might help here:
  • .Env Header
    • General Env Variables
  • Env.Laravel Header
    • Auth
    • Logging
    • Database
    • Email
    • etc
• The preparation section was a bit confusing for me. They're good questions that users should be asking, but perhaps most of it can be repurposed in a prominently highlighted "How to optimize your setup" post-install section?
  • Database - I have been self-hosting for a year or so bunch of containers but not sure if I have a managed postgres database already, whether it's local or in docker, etc. It's introducing an (uncertain) can of worms that makes me unsure about what subsequent setups. For me, I want the container to make whatever decision is the default for the majority of other existing containers. If there's a drawback to making this decision for users (ie they might have to migrate data down the road), that might be
  • Sending Email - What is a transactional email service? If that is something like gmail/proton, then perhaps it can be referenced explicitly? Also, unless there's a clear resources that users can be directed to in order to grab this content in < 5 mins, it is likely creating too much friction.
    • IMO, I think it should default to the log, with a passing reference to the idea of a side-project of setting up an SMTP
    • grep yourEmail@Address.com -A20 logs/laravel*.log

Installation-related

• (I think this might only apply to the non-traefik install) If APP_FORCE_HTTPS is set to false, then the user needs to also input the following or else the register/login page does nothing
  • SESSION_SECURE_COOKIE=false
  • SANCTUM_STATEFUL_DOMAINS=localhost,127.0.0.1,<insert domain:IP>
  • Re: security here, I'm using LAN-only for the most part, and tailscale as a VPN to wrap a security blanket around the http connection
• Remind users that the db username/pw/port in the .env needs to match the db username/pw/port in laravel.env or it will error out. (Perhaps self-explanatory, but I somehow made that error 😭)

FAQ/Troubleshooting

• This can highlight 'obvious' user-error, such as:
  • Error message when the postgres tables aren't present because the user skipped the necessary step
  • Error message when the db info in .env doesn't match the laravel.env info

Great project overall tho and looking forward to using it more. I've spent more time giving feedback than actually using it, but I can write up a doc-related PR in the near future if it's desired but no one else wants to do it.