Document how to use a different web-root instead of 'web'

[weitzman]

Acquia Cloud requires Drupal in a subdir named 'docroot' but this project uses 'web'. The 'web' name is used in scripts in addition to composer.json. Is there some better solution for changing this than find/replace? Would be good to document this somewhere (I volunteer).

[deviantintegral]

I put a symlink from web to docroot in the project repository, and then ignored docroot from code indexing in PHPStorm. I'm not sure if Acquia lets you serve from a symlink, but I imagine you could rename web to docroot, and then make web the symlink.

[greg-1-anderson]

I use 'drupal' in pantheon-systems/example-drupal7-circle-composer, and I have also seen htdocs and code.

I'd like to use the same directory name in my project as is used here. It doesn't matter to me very much which one we use; if I'm going to have to rename my root directory anyway, 'docroot' is as good of a choice as any.

If we can agree that it makes sense to standardize on docroot, I'll make a PR here to do it, and convert my project over as well.

[webflo]

I would go with web. Many people use the template already for D7 and D8. web is default in https://github.com/symfony/symfony-standard as well.

[greg-1-anderson]

Okay, I will switch to web to follow the standard here and in symfony.

[webflo]

@weitzman Maybe we can revisit this issue and provide a template without the scaffolding files after #77 went in.

[greg-1-anderson]

~So, it turns out that I have to use code when using Drupal 8 on Pantheon. This limitation should not be around forever; once the restriction is lifted, I'll switch back to web in my fork.~

~When using drupal-composer/drupal-scaffold, it is very easy to change the location of the Drupal root--and is getting easier. It might be nice to make scripts/composer/post-install.sh a function of drupal-scaffold. If we also defined the placeholder folders such as modules/contrib in composer.json, and had drupal-scaffold create those as well, then we could probably remove the web directly altogether.~

[RoSk0]

Is it possible the directory name to be configurable?

[greg-1-anderson]

If we removed the web directory, then the only references to the document root would be in the composer.json file and the post-install script. We might be able to have post-install read composer.json and pick up the location of the document root by checking the location of drupal/core; however, there are multiple references to the document root in the composer.json file. You could maybe factor those out to a single reference by adding variable replacement support to composer/installers, but I don't know if such an enhancement would be welcome or not.

[greg-1-anderson]

The latest version of #77 makes it pretty easy to change the directory name on the fly. There are still a couple of files where it needs to be changed. Unfortunately, the composer command-line tool will not divulge the installation location of a component. You can do it from a custom installer, but, as I mentioned in #77, I recommended that post-install.sh should be kept a shell script so that it is easier for folks to customize.

[greg-1-anderson]

77 / #105 have been merged, so relocating the docroot from web to something else now requires modification of only a few files:

1. composer.json (several locations)
2. .gitignore (several locations)
3. post-install.sh (only DOCROOT variable at top of the script)

We could in principal read DOCROOT from composer.json in post-install.sh, but it would still be necessary to make multiple changes to composer.json and .gitignore, so perhaps this is not worthwhile.

Perhaps we should leave this as a customization to be done by the end user?

[deviantintegral]

This feels like there's enough site-specific components to this that trying to automate more probably isn't worth the effort. Let's just make this a task to document the steps above? So far they're working fine for me.

[weitzman]

Yes, a docs PR sounds about right. Symlink is simplest solution for many.

[gambry]

relocating the docroot from web to something else now requires modification of only a few files:

composer.json (several locations)
.gitignore (several locations)
post-install.sh (only DOCROOT variable at top of the script)

After #128 now files are:

• composer.json (several locations)
• .gitignore (several locations)
• scripts/composer/ScriptHandler.php

But as @weitzman is suggesting a symlink is still the simplest solution ("web" -> "any" or "any" -> "web").

[webflo]

We could follow symfonys model and add some extra config to our composer.json and use in our ScriptHandler. see https://github.com/symfony/symfony-standard/blob/master/composer.json#L53

[greg-1-anderson]

That's a great idea, but I think it would need to be a feature of Composer Installers. It would be better as a feature of Composer Installers, anyway, as it seems like it would be commonly useful to be able to do replacements from extra config in destination paths -- and Composer Installers already supports replacements in paths.

[gambry]

@greg-1-anderson so far composer Installers supports replacements in paths based on package $name, $vendor, $type. Do you think having project based replacements will be a feature they would take in consideration?

If they won't, I would see it more like a composer script, which ask for docroot folder name, update the composer.json paths and add an extra configuration parameter to be used in ScriptHandler.

[joelpittet]

Just wondering because I am planning on doing this. Could you create a relative symlink from docroot(or whatever you prefer) to web?

[greg-1-anderson]

@joelpittet Yes, some folks do that; should work in most environments.

[nalipaz]

Could we use a composer config variable for this? I was just thinking on this and it might be a simple solution.

[greg-1-anderson]

See my previous comment. The docroot variable exists in a few plain text files. Some fixup is required if the user wants to select something else.

[nalipaz]

We could in principal read DOCROOT from composer.json in post-install.sh, but it would still be necessary to make multiple changes to composer.json and .gitignore, so perhaps this is not worthwhile.

To that remark, wouldn't it be possible to store the value of the docroot in composer config, maybe composer config documentroot something and then apply it in the composer.json with a "{$documentroot}/modules/contrib/{$name}": ["type:drupal-module"], as an example? I would assume the variable should be able to be obtained in the post-install.sh too. That only leaves the .gitignore which could be edited manually by most or we could go so far as to sed it to the correct value if it is set, or perhaps change to a wildcard for simplicity.

[greg-1-anderson]

@nalipaz Yeah, that would work for sure. The one wrinkle is that at the moment, we use composer/installers to remap the module install locations, and it does not support a {$documentroot} substitution. At least, in the past it didn't. If you know how to make that work today with a composer config, then a PR to demonstrate that would be most welcome.

[nalipaz]

@greg-1-anderson I appreciate the details on that. I can't say I know how to make that work and was only speaking theoretically here since it seems the most integrated way. If I can gather a moment I might try my hand at the idea and of course others are welcome to try as well.

[fabean]

I locally changed the following: • composer.json (several locations) • .gitignore (several locations) • scripts/composer/ScriptHandler.php

To say "docroot" instead of "web" but I'm still not getting the root files in docroot like index.php. I know those come from the drupal-scaffold project but I don't have this issue when it's under /web. Is there another hidden config location I cannot find?

[fabean]

Okay, I lied... Totally works it must have been a composer cache or something that kept wanting to put things in /web. Sorry.

[webflo]

@fabean Please review https://github.com/drupal-composer/drupal-project/pull/255. This removes the requirement to change the ScriptHandler

[kevinquillen]

Just tried to deploy to Acquia - docroot symlink did not work for me at all (Pro tier). It kept giving the default Acquia page when no code exists.

Switching to Live Development mode brought it up, but I don't work in that way.

I had to mv web docroot and create a local symlink for web so Docker continued working. That got Acquia up and going.

[cgmonroe]

I think this could be resolved now by adding an FAQ entry to the ReadMe like this:

To use a different web root directory, e.g. docroot instead of web:

1. Create the project without installing it using the --no-install option. e.g.:

composer create-project drupal-composer/drupal-project:8.x-dev my_site_name_dir --no-interaction --no-install

2. cd into the project directory and edit the 'installer-paths' section in the composer.json file. Replace the web/* paths with the web root you want, e.g. docroot/

3. Finish the install using the command:

composer install

[webflo]

@cgmonroe Good idea, please submit an PR.

[greg-1-anderson]

The post-install script now uses Drupal Finder to locate the web root, so only .gitignore and the composer.json files would need to be modified to use a different location.

[simesy]

You wouldn't necessarily want to add /docroot to .gitignore anyway, since you'd likely be on Acquia, and their culture is to commit docroot.

[greg-1-anderson]

The documentation should not presuppose that Acquia is the only reason someone would want to use a different directory name for the Drupal root. It would be worthwhile to discuss how to adjust the .gitignore file for environments where vendor et. al. are committed.

[simesy]

Agreed, I'm just saying that in my experience jumping around between vendors and dev tools, you're getting down to edge cases with that one. That's a gold stamp :P

[simesy]

I would probably add both /docroot and /web to gitignore, as these are the only two drupal webroots I've ever seen... and I've never seen them used for anything else (in Drupal project context). Or comment out /docroot with inline comment, which is the ideal for any new person reading it.

[michaellenahan]

With credit to @cgmonroe here is the PR for the changes to the README: https://github.com/drupal-composer/drupal-project/pull/527

[Juc1]

Hi all re https://github.com/drupalcommerce/project-base/blob/8.x/composer.json

Just before the installer paths there is

"drupal-scaffold": {
            "locations": {
                "web-root": "web/"
            }
        },

https://github.com/drupal-composer/drupal-project/pull/527/commits/236d1f02cc4cd6297edbb05590fd18b84c05add3 mentions installer paths. Do I also need to change web-root ?

[greg-1-anderson]

The previous comments referred to the changes needed when using drupal-composer/drupal-scaffold. Now that this project is using drupal/core-composer-scaffold, you should change the web-root setting as well.

[Juc1]

@greg-1-anderson ok thanks

[alexpurser]

quick novice question please and apologies if ive misunderstood - my webserver creates a docroot - say vhost1 - and i create a drupal project which is now accessible via browser from URL/web. If I want to be able to access the site via URL what are the steps i must follow including any tidying up.. im sure ive read that the composer.json file shouldnt be in the same folder that is visible from the web.. i guess im looking for a best practice guide here keeping it simple for the new guy!

[deviantintegral]

The best / easiest solution is to keep your code in the same place on disk, but change the docroot to <current path for docroot>/web. It's not recommended nor typically supported these days to have the top-level directory you have access to also be the docroot.

[leymannx]

@alexpurser – You simply have to point your vhost or domain to the web/ folder inside the project. So /var/www/myproject/web instead of just /var/www/myproject. It's bare server configuration. And outside of the scope of this project.

[alexpurser]

Hi Norman im afraid im constrained by the server which creates the web root directories for vhosts directly under its vhost directory - .../vhost/A, .../vhost/B. ,,,etc. It is non trivial change on the server i am using (Nethserver dist of Centos) so, for the purposes of this question at least, im bringing it back into scope for this project if I may!

[greg-1-anderson]

This project does not support web hosts that require the Drupal root be at the project root. If you are using such a host, you could try looking at drupal/legacy-project.

[NielsSluijs]

@alexpurser, I've solved a similar problem by placing the project in a separate directory and replace your "web-root directory" with a symbolic link to the web/ folder.

[AlexSkrypnyk]

This issue is about documenting the usage of a different web root.

Before we can document this, we need to decide if this project should provide a symlink from docroot to web to demonstrate that this is possible (using docroot, which happens to make this project Acquia-compatible out-of-the-box).

If yes - than we need a PR with a docroot as a symlink and a readme explanation on how to change that. Do note that if we decide to go this way, than it will not be a simple find/replace of docroot with your_docroot because there are several places where the document root is referenced.

If no - we can just document that it is possible to use a symlink, but there could be some side effects.

[deviantintegral]

After recommending the symlink solution in 2015, it’s not something I recommend anymore. Challenges I’ve seen include:

• Developers not knowing they should omit the symlink from IDE indexing, leading to significant performance hit.
• Difficulties with symlinks on Windows hosts
• While ddev didn’t exist in 2015, and now does a good job of managing code mounts with symlinks, I’ve seen issues for projects that are using docker compose directly and mess up code syncing, leading to either the symlink not being preserved and duplicate code being synced, or for conflicts syncing changes back out such as after a composer install.

I think the best thing to do is to link to https://github.com/drupal/core-composer-scaffold?tab=readme-ov-file#defining-project-locations and call this done

[leymannx]

-1 for symlinks from me too.

Can't we pick up the webdir name from composer.json in scripts? This would make it relatively easy to have the webdir changed in just composer.json.

[AlexSkrypnyk]

cool, we have 3 supporters for not doing symlinks. Let's just document the process of how it can be updated, if needed.

[leymannx]

Is there no way to have a variable path name in the installer-paths? Something like "[web-root]/core": ["type:drupal-core"], 🤔

[adityajoshi94]

@greg-1-anderson Moving to year 2024 , can we create a symlink in pantheon hosting from Drupal webroot ?
Desired symlink as follow /web/robot.txt to web/site/default/files/robot.txt.