Create a complex Multisite Setup

There are already numerous topics about Multisite Setups on this forum and also on other places on the internet, I’m aware of that. Still none of them seems to solve the problems I’m having.


I’m trying to create a more complex multisite setup I can use to host multiple websites through one Grav installation. This should make maintenance of these websites easier, since I don’t have to do every step for every website but just one step for all at the same time.

Currently, I have about five active websites, but they are getting more over the time. I host them all on the same shared server though a Cloud Provider. Each website has its own but identical Grav core, which is a fork with some modifications (only some scripts, …) and the website as a skeleton (the user dir). I install dependencies via the .dependencies file using the built-in command.

This variant already works great for me, since I just have to clone the modified core to . and the skeleton to ./user, and run an installation script which installs the dependencies and gets some secrets.


What I expect from the multisite setup is that I have only one Grav core, and all the websites as skeletons in the user/env folder. I’d like to use shared dependencies, so I only have to update a plugin one time and not n times.

Since those websites are independent, they should have their own cache, logs, … folder (like cache/website1 or user/env/website1/cache).

Once I have this multisite setup working on a local dev environment, I want to be able to just move the websites’ user dirs from the single core to the multisite core (and eventually run a short automated script to create cache folders, …)


I started creating this multisite setup on my local dev env, following the official docs. Now I’m having some different problems I tried to solve for a few hours, but I’m still stuck on them.

I’ve created the setup.php file using the setup_subdomain.php template (which should also work for normal domains, right?) and started figuring out what needs to be done in the streams.yaml file in the skeletons’ config. The dirs in prefixes are also created.

    type: Stream
      '': ['environment://images', 'system://images/']
    type: Stream
      '': ['cache/domain.tld']
      images: ['images/domain.tld']
    type: Stream
      '': ['logs/domain.tld']
    type: Stream
      '': ['backup/domain.tld']


These are the current problems I’m trying to solve:

1. Installing dependencies

When trying to install the dependencies with symlink (bin/grav install user/env/domain.tld --symlink), it gives me an error:

Symlinking Bits

No local configuration available, aborting...

What is this local configuration?

Neither running the command without the --symlink flag works, since it would install the dependencies in user/env/domain.tld/user/plugins instead of user/env/domain.tld/plugins.

2. Missing Theme

When I manually added the dependencies and symlinked them (from env to user), I got the next error: Somehow, it doesn’t get the local theme (styling options specific for each website, code in the skeleton), but instead just the next one of the inheritance chain. (I use the Quark theme, which some more options through the Open Publish theme. Then there’s my own theme I use for all websites and at last, the local theme. Yes I know, I’m working on flattening it.)

It doesn’t use the theme templates, although it should because of the config. Therefore, no favicon, header image, or styles and scripts get loaded.

I’ve somehow found a workaround by using
{% do assets.addCss('themes://local/css/custom.css') %}
instead of
{% do assets.addCss('theme://css/custom.css') %}.

But this isn’t a permanent workaround, since these all have to be manually changed in all the themes for it to work.

3. Error loading theme

Because of error #2, I dug deeper into the debugger and found out the themes stream is wrong (it tries to get it from user://themes, but the local theme is in env). Therefore, I tried by adding it to the streams.yaml file so it should get the themes from the environment:

    type: Stream
      '': [ 'environment://themes' ]

This only resulted in breaking Grav with the error:

Template "@quark-open-publishing/partials/base.html.twig" is not defined in "partials/base.html.twig" at line 1.

I also tried by adding user://themes to the prefix, which got me back to Problem #2. Neither adding the theme stream to streams.yaml with environment://themes/local in the prefix array has worked.

This whole thing gives me headache and I’m no longer confident this could work as I expected at first. Does anyone have a multisite setup like I need and would like to share it with me? Or is there someone who had the same problems?

I’m also happy to hear other ideas and recommendations to achieve something similar.

If someone would like to see the whole skeleton, check out GitHub - Crabston/grav-demo at multi-site-setup.

I’ll be on vacation starting Saturday for 2 weeks without my laptop, so I won’t see any replies. That’s why I described every detail, so I don’t need to add more details when I’m away.

I had a multisites working, it solved the problem of multisites on shared hosting which only allowed 1 domain. Now I don’t need it but may be able to help.

After playing with streams, I too gave up and devised a simpler solution.
just using a few soft links and the standard setup.php

In simplistic form
Follow the guide for multisite

Assuming its a LInux based host - use Linux links as windows links will not work.

From the subsite use soft links to the relevant base directories for any common files.
Any directory in the env/sub-site folder will be overeride base settings.

e.g. Put all plugins in the base site and replace env/sub-site/plugins with a relative softlink ../../plugins for all
in the env/sub-site/plugins use soft links for individual plugins you want to include, these can be controlled for each separate site within config/plugins/

Similary for themes, use symlinks back to base for common folders/files, and/or add in folders and files for those specific to the sub-site.

Streams (e.g image) would apply to the subsite but access the info from the base site via link if required.
So if using all common images stream across in subsite replace env/images with a link other wise you can replace individial files with links if you really want to.

Note: Multiple Admins can be an issue, update or add plugins via the base admin.
The subsite admin can be used to editing pages config’s etc.
If you run Admin from the subsite to update you run the risk of a mismatch of versions.

Note 2 Some shared hosting will not allow you to create links.
Just recreate the ‘relative’ links (Linix not windows) in a local folder and zip the folder, eg. Upload file then unzip it

Aplogies for the vague reply, it looks complicated - but isn’t
A full reply would be even longer and more complicated with more options.
I hope this helps