BoltCM

Sophisticated, Lightweight and Simple

Jump to docs navigation
Edit on GitHub

Howtos » Troubleshooting 'Outside of the web root'

Sometimes, especially on shared web hosts, it's not very simple to change the web server configuration to point to the public folder that comes with the archive install files that you can download as .tgz or .zip files.

There are three ways to 'fix' this:

Finally, at the end of this page, there's a brief explanation of why it is important to keep your files outside of the web root: What's the point of doing this?

Configure Apache or Nginx

If you have access to Apache or Nginx's configuration files, you can modify those to use the public folder as web root. For more information about this, see the pages on configuring Apache or Nginx.

Sometimes this is even possible from the web hosting Control Panel, like Plesk or DirectAdmin.

Configure Bolt to use the web host

Often you'll have a folder structure like this, on your web host. As you can see, it doesn't have a public folder, but a www folder instead. Sometimes this is called public_html, html, web or DEFAULT. This example works the same, just substitute www for whatever your web root is called.

.
└── example.org/
    ├── logs/
    ├── stats/
    └── www/

To get Bolt working, do the following:

paths:
    cache: app/cache
    config: app/config
    database: app/database
    web: www
    themebase: www/theme
    files: www/files
    view: www/bolt-public/view

The result in the folder will look like this:

.
└── example.org
    ├── .bolt.yml
    ├── app/
    ├── extensions/
    ├── logs/
    ├── README.md
    ├── stats/
    ├── vendor/
    └── www/

After this, you should be good-to-go, and Bolt will work correctly.

Often you'll have a folder structure like this, on your web host. As you can see, it doesn't have a public folder, but a www folder instead. Sometimes this is called public_html, html, web or DEFAULT. This example works the same, just substitute www for whatever your web root is called.

.
└── example.org/
    ├── logs/
    ├── stats/
    └── www/

To get Bolt working, do the following:

The result in the folder will look like this:

.
└── example.org
    ├── .bolt.yml
    ├── app/
    ├── extensions/
    ├── logs/
    ├── public/
    ├── README.md
    ├── stats/
    ├── vendor/
    └── www -> public

After this, you should be good-to-go, and Bolt will work correctly.

Use .htaccess to change the web root

As a last resort, you can modify the .htaccess file to 'proxy' the public/ folder. This is described in a tip from Siteground.

Let's say that by default your website is loaded from the public_html folder of your account. This public_html directory is effectively the web root folder or document root folder. If you've placed all Bolt files in this folder, and want to 'serve' Bolt's public to be displayed when you type your domain name, add the following lines to the .htaccess file in the public_html folder:

RewriteEngine on
RewriteCond %{HTTP_HOST} ^domain-name.com$ [NC,OR]
RewriteCond %{HTTP_HOST} ^www.domain-name.com$
RewriteCond %{REQUEST_URI} !^/?public/
RewriteRule (.*) /public/$1 [L]

In the above lines you should replace domain-name.com with the hostname of your site.

Move the files outside of the public folder

If you are hell-bent on flattening the file structure , you can do that as well. Follow the following steps:

First, move all files and folders from public/ one level up. Don't forget to include the .htaccess file in there. Then remove the public folder.

You will now have a structure that looks like this.

.
└── example.org
    ├── app/
    ├── bolt-public/
    ├── extensions/
    ├── files/
    ├── theme/
    ├── thumbs/
    ├── vendor/
    ├── .bolt.yml
    ├── .gitignore
    ├── .htaccess
    ├── README.md
    └── index.php

Edit your .bolt.yml, so that Bolt knows about the changed structure, basically removing public/ from it:

paths:
    cache: app/cache
    config: app/config
    database: app/database
    web: .
    themebase: theme
    files: files
    view: bolt-public/view

Finally, edit index.php, so the bootstrapping can load successfully. Find the line with the require in it, and change it like this:

$app = require dirname(__FILE__) . '/vendor/bolt/bolt/app/web.php';

What's the point of doing this?

Sometimes people ask if we're not making things 'needlessly more complex' by putting most of Bolt's files outside of the web root. While we agree that it might be a very minor nuisance if it's the first time you're doing it like this, we do believe this is a very good practice.

Security

The major benefit is security: It's widely accepted to be "best practice" to keep as many PHP files outside of the web root as possible. What we're doing by putting files outside the web root is basically making sure they are not accessible through a web browser. Simply put, everything that's not readily accessible from the outside world is that much harder to exploit. As you might know, Bolt uses Composer and a lot of external packages. While all of these packages are tested thoroughly by a lot of developers, there's always a chance that a security issue might slip through the cracks. If this happens, and the 'security issue' is not accessible at all, your website and your visitors will still be safe.

The same holds true for your configuration files: These files will contain Database credentials, privacy-sensitive information and perhaps key/secret pairs for some external API. While you can 'protect' these files with .htaccess or your Nginx configuration, it's still more secure to keep these files in a location where they aren't accessible at all.

Maintenance benefits

The Symfony framework uses a similar structure by default, and we're following their example: How to Override Symfony's default Directory Structure

Doing this makes maintenance and upgrading more straightforward, because your custom files are only in a few distinct places. All other files can just be replaced, without having to worry about overwriting your configuration files, for example.


Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on IRC.
Spotted a typo, or have something to add? Edit this page on GitHub.