Set up Grav 2.0 with Admin

[openscript]

I was following https://learn.getgrav.org/20/basics/installation and have troubles to set up Grav 2.0, but don't know how to set up Admin. I've used composer create-project getgrav/grav ~/webroot/grav to set up the project.

First the zip extension was missing, so it just downloaded some old Grav 1.0 version. After figuring this out, I started over and Grav 2.0 was installed.

Now I try to figure out, what is the way to set up the Admin UI. I've figured out that with ./bin/gpm install plugins can be installed. When I run ./bin/gpm install admin the old Admin UI is installed.

It feels like the whole documentation is a mix between old Grav 1.0 and Grav 2.0 and the newer parts are just generated.

Is this really the case?

What is the right way to install admin?

[rhukster]

Hey, sorry for the rough ride. Short answer first, then the three things you found that were genuinely broken on our end, all of which are now fixed.

Installing admin on Grav 2.0

Grav 2.0 replaced the old monolithic admin plugin with two plugins: api (the REST backend) and admin2 (the SPA that talks to it, branded Admin Next). admin2 declares api as a dependency, so one command gets you everything:

cd ~/webroot/grav
bin/gpm install admin2

GPM resolves the whole chain for you (api, then login, form, email, shortcode-core) and prompts once to install the dependencies. Say yes. When it finishes, open https://yoursite/admin. Admin Next serves on the same /admin route the classic admin used, and because your site has no user accounts yet it walks you through creating the first administrator right there. No bin/plugin login newuser, no editing config by hand.

If you would rather not install anything separately, https://getgrav.org/download/core/grav-admin/latest is core with api and admin2 already bundled. Worth knowing that there is no composer create-project getgrav/grav-admin equivalent; that bundle only exists as a zip.

bin/gpm install admin should not have worked

You were right to be surprised. The classic admin plugin's manifest declared only a floor of grav >=1.7.49, with no upper bound and no compatibility block at all, so GPM looked at your 2.0.22 and saw nothing wrong. I've added the missing declaration, so classic admin now correctly identifies itself as 1.7 only.

That is the manifest half. The other half is that GPM's install path never checks compatibility metadata at all, only minimum versions, even for packages like admin2 and api that do declare it properly. So the declaration fixes what bin/gpm index reports but does not yet block the install. That gate is the next piece of work and I'm scoping it now.

The docs

Nothing is AI-generated, but your instinct that it is a mix was exactly right, and the mechanism is worse than "unfinished". The /20/ tree falls back to the /17/ tree for any page without a 2.0 rewrite, so roughly 148 Grav 1.7 pages were being served at /20/ URLs with nothing telling you they were old. /20/plugins/plugin-install was one of them, which is why it described the classic admin's Plugins then Add button. Several hosting guides under /20/webservers-hosting/ were cheerfully telling people to run bin/gpm install admin. And /20/basics/installation was a real 2.0 file we simply never finished: PHP 7.3.6 (while the requirements page one click away said 8.3.11), 1.7.0 download links, 1.x-dev, and no admin install section anywhere. Nowhere in the entire 2.0 documentation did the words bin/gpm install admin2 appear.

Now fixed: the installation page has a proper "Install the Admin Panel" section, the PHP version is corrected in both places it appeared, the download list and composer instructions are 2.0, there is a real 2.0 plugin-install page, the extension list on the requirements page is accurate, and the fallback is suppressed for the chapters where a 1.7 page gives an actively wrong instruction rather than merely a dated one.

The zip extension

This one is nasty and you diagnosed it correctly. Grav has required ext-zip since 1.1.0 back in 2016, but composer create-project with no version constraint does not fail when a requirement can't be met. It walks backwards until it finds a version your environment does satisfy, which with zip missing is Grav 1.0.10, from before the requirement existed. I reproduced it exactly: Composer prints one line saying it can't use 2.0.22, installs 1.0.10, and the error you eventually see is an unrelated-looking complaint about doctrine/cache wanting PHP 5.5. Nothing about zip anywhere.

The fix, now in the docs, is to pin the major version:

composer create-project getgrav/grav ~/webroot/grav "^2.0"

With the constraint pinned, the same broken environment gives you a hard error naming the missing extension instead of an eleven-year-old CMS. I've also added the extensions core was using but never declaring (ctype and session, both called unguarded), which narrows how far back the resolver can escape in the first place.

Thanks for writing this up properly instead of just giving up. Four fixes across four repos came out of it.

— Andy

[openscript]

Thank you Andy, for taking the time to answering me. I've run through the setup again and have everything working locally now. I used Grav 1 a couple of years ago for a client project, and I'm really impressed with how far it's come since then!

I have one follow-up question. When I install plugins or create user accounts, they get stored in subdirectories of the user folder, which are git-ignored by default. What approach would you recommend for managing plugins (dependency management) and accounts within a team that uses git?

[hughbris]

FWIW I'll tell you how I manage (just me) deploying themes and plugins between environments with git.

Create .dependencies files in your user folder. These are similar to composer.json and other build config files that are probably familiar. So you run bin/grav install from the Grav root directory and it will consult this YAML file. Find an example in Grav core and it is also briefly outlined in a skeleton context in the docs. (I don't use skeletons, but that might also be another team deployment strategy.)

Note that some plugins may require you to run composer install after installation, as they don't populate the vendor directory.

I'm not crazy about the file format. It has redundancy and is a slight pain to maintain but it does the job well. To manage different environments, I put a .dependencies file in each environment directory (user/env/<hostname>/.dependencies) and then symlink to the right one from user in each environment. Your requirements will probably differ.

I push user/accounts and other gitignored files with rsync. With a team, I imagine each user will only need to manage and store their own local credentials. I'm sure you could script as much of this as you wanted.

[openscript]

When running bin/grav serve the following line is printed:

sh: 1: exec: symfony: not found

Probably grav tries to use symfony by default and reverts back to the embedded server if not installed. Maybe it would be a bit cleaner to hide this line.

[openscript]

Thanks @hughbris for your answer! I think .dependencies works for me too. Do you only keep the user folder in your repository or also the rest of grav? I'm thinking about to delete test and other folders or maybe even have a script that composer create-project getgrav/grav ./grav "^2.0" and then symlinks the user folder to grav/user.

[hughbris]

Do you only keep the user folder in your repository or also the rest of grav?

Only user. I use docker for the core parts, which makes it easy to manage upgrades once you get your head around docker. I feel like I could write a small book about my setup and we're probably going too off-topic for this thread anyway.