New install went poorly - Feedback and Questions

nadnerb

The issue

This is more of a general feedback post. I resolved my issues but I feel that what I went through could have been avoided had I known several crucial details. I also have questions as to why certain things are they way they are.

To start: I am using Laravel Forge as the server environment (which I figured wouldn't be a problem since Flarum is supposedly based on it and symfony). VPS is a DigitalOcean 1vcpu/1GB/25GB.

Issues:

Lots of issues related to missing directories. The php-fpm user is the owner of the root folder where flarum is installed (and all subfolders) with 775 perms as indicated in the docs by running chmod 0755 -R <dir>
- public/assets, storage/cache, storage/formatter, storage/sessions all had to be created manually because for some reason Flarum would not even attempt to create them. Does Flarum just not try to create these folders? Why not? I have no issues creating directories with Laravel in the exact same environment setup.
- if the above dirs are required to function, why not simply create them. Or a least list them as required in the installation docs.
Very confusingly, I ran the install via the browser and was automatically logged in (somehow) but could not log out without clearing cookies.... but then I couldn't log back in. All routes complained of CSRF token mismatch, which I think ended up being the storage/sessions dir not existing. That said, the expiration of my flarum_session cookies were at the exact time of the initial page request, so I also updated PHP's timezone to be "America/New_York" as well. I'm not sure which change (or perhaps it was both) fixed this issue.

Some of these issues were likely caused by git not adding empty dirs to the repo when I pushed, however I feel that directories existing is not a safe assumption to make in an application.

I did modify the Forge deploy script as following. This should take care of most of the issues (aside from possible TZ issue) that I encountered.

cd /home/forge/redacted.example.com
git pull origin $FORGE_SITE_BRANCH

$FORGE_COMPOSER install --no-dev --no-interaction --prefer-dist --optimize-autoloader

( flock -w 10 9 || exit 1
    echo 'Restarting FPM...'; sudo -S service $FORGE_PHP_FPM reload ) 9>/tmp/fpmlock

mkdir -p public/assets
mkdir -p storage/{cache,formatter,less,locale,logs,sessions,tmp,views}

chmod 775 -R ./

if [ -f flarum && -f config.php ]; then
    $FORGE_PHP flarum migrate
    $FORGE_PHP flarum cache:clear
fi

Questions:

Why doesn't php flarum migrate exist until flarum is installed? I think it would be a better approach for new users to be told that you can't migrate until it's installed and a) please visit your site url to install or b) run php flarum install instead of just complaining that it's not a command. I thought I had missed something after the composer create-project instruction.

Flarum information

Flarum core: 1.8.9
PHP version: 8.3.17
MySQL version: 8.0.41-0ubuntu0.24.04.1
Loaded extensions: Core, date, libxml, openssl, pcre, zlib, filter, hash, json, pcntl, random, Reflection, SPL, session, standard, sodium, mysqlnd, PDO, xml, bcmath, calendar, ctype, curl, dom, mbstring, FFI, fileinfo, ftp, gd, gettext, gmp, iconv, igbinary, imagick, imap, intl, exif, msgpack, mysqli, pdo_mysql, pdo_pgsql, pdo_sqlite, pgsql, Phar, posix, readline, shmop, SimpleXML, soap, sockets, sqlite3, sysvmsg, sysvsem, sysvshm, tokenizer, xmlreader, xmlwriter, xsl, zip, memcached, redis, swoole, Zend OPcache
+----------------------+---------+--------+
| Flarum Extensions    |         |        |
+----------------------+---------+--------+
| ID                   | Version | Commit |
+----------------------+---------+--------+
| flarum-flags         | v1.8.2  |        |
| flarum-approval      | v1.8.2  |        |
| flarum-tags          | v1.8.3  |        |
| flarum-suspend       | v1.8.4  |        |
| flarum-subscriptions | v1.8.1  |        |
| flarum-sticky        | v1.8.2  |        |
| flarum-statistics    | v1.8.1  |        |
| flarum-mentions      | v1.8.5  |        |
| flarum-markdown      | v1.8.1  |        |
| flarum-lock          | v1.8.2  |        |
| flarum-likes         | v1.8.1  |        |
| flarum-lang-english  | v1.8.0  |        |
| flarum-emoji         | v1.8.1  |        |
| flarum-bbcode        | v1.8.0  |        |
+----------------------+---------+--------+
Base URL: https://redacted.example.com
Installation path: /home/forge/redacted.example.com
Queue driver: sync
Session driver: file
Mail driver: mail
Debug mode: ON

luceos

nadnerb Does Flarum just not try to create these folders? Why not? I have no issues creating directories with Laravel in the exact same environment setup.

Flarum does exactly the same thing as Laravel, truth be told. All directories do exist when cloning or using composer, but if you commit your project to git you will need to include all .gitignore files in these empty directories to force these to be committed. If you installed using git, this would probably already have been the case.

nadnerb f the above dirs are required to function, why not simply create them. Or a least list them as required in the installation docs.

Because under normal circumstances these exist. But if you push your project to git and then deploy from there without include said directories (and their gitignores to force that), it will fail.

nadnerb Very confusingly, I ran the install via the browser and was automatically logged in (somehow) but could not log out without clearing cookies.... but then I couldn't log back in. All routes complained of CSRF token mismatch, which I think ended up being the storage/sessions dir not existing. That said, the expiration of my flarum_session cookies were at the exact time of the initial page request, so I also updated PHP's timezone to be "America/New_York" as well. I'm not sure which change (or perhaps it was both) fixed this issue.

This is likely a result from missing directories indeed.

nadnerb Why doesn't php flarum migrate exist until flarum is installed? I think it would be a better approach for new users to be told that you can't migrate until it's installed and a) please visit your site url to install or b) run php flarum install instead of just complaining that it's not a command. I thought I had missed something after the composer create-project instruction.

Because you can't migrate on a database that's not configured. Allowing the command to exist will throw another error, we would have to capture, render an human readable error for or explain during support requests.

If you come from Laravel, you will notice more of these decisions that mark the difference between a developer oriented framework and an end-user software product.

nadnerb

luceos If you come from Laravel, you will notice more of these decisions that mark the difference between a developer oriented framework and an end-user software product.

Maybe I misunderstand you- are you saying that Flarum is an end-user software product or a developer-oriented framework?

I think an end-user product would give friendlier errors, especially during setup (such as directories missing, etc).

I don't think what I did was unusual (regarding putting the install in a git repo). I just double checked and although you have .gitignore files inside of each of the storage/** directories (in the official repo), they are not present after composer create-project, so that may be something to look into? At the very least, perhaps a .gitkeep? The root .gitignore also wasn't present. Not knowing the project well enough, I'm not sure if this is intentional or not.

In any case, I'm not trying to be difficult/obtuse, so apologies if that's how I am coming off. I have had to solve a lot of these types of issues in my own projects so I figured I'd provide feedback as a developer first-time user. It may simply be a difference in opinion, but I think QoL changes shouldn't be ignored.

All the best

luceos

nadnerb I just double checked and although you have .gitignore files inside of each of the storage/** directories (in the official repo), they are not present after composer create-project, so that may be something to look into?

That would indeed be very worrying. I'll look into it.

nadnerb In any case, I'm not trying to be difficult/obtuse, so apologies if that's how I am coming off.

Not at all, I think it's great of you to take your time to report back your findings. It's much appreciated!

luceos

Weirdly it seems storage contains the right folders, what version have you installed?

luceos

I remember that in some scenario's I had the same happen to me, especially when trying to store the project into git. @SychO and I just ran a few tests and narrowed it down to the following steps:

install flarum using composer create-project
.gitattributes will cause .gitignores inside storage subfolders (and public/assets/avatars) to be removed, making them empty
attempting to store installation in git will make git not see these empty folders

As a consequence we made a change to the skeleton (flarum/flarum) for 2.x where we ensured the gitignore files will now remain part of the installation through composer.

nadnerb

I ran composer create-project flarum/flarum:^1.8.0 . inside a directory I created (e.g. ~/Sites/flarum)

The directories are there, but no .gitignore files at all like in the repo on github. So, when I did git add . initially, I noticed that the entire vendor dir was included. So I git reset and went to github, grabbed the root .gitignore from flarum/flarum and repeated git add . and figured I was good. I didn't search through subdirs to check for other .gitignore occurrences, leading to the errors I encountered.