--- /dev/null
++++
+title = "Filesystem Permissions"
+description = "The file and folder permissions required by BookStack"
+date = "2023-02-27"
+type = "admin-doc"
++++
+
+BookStack requires the ability to write and read files for various uses such as writing
+logs, handling file uploads and running application code.
+Ideally, files permissions should be limited to just what's required to reduce the chance
+of potential vulnerability exploit.
+
+By default, BookStack requires the following permissions:
+
+- Read access to the BookStack install folder and everything within.
+- Write permission to the following folders, relative to the BookStack installation directory, and everything within:
+ - `storage/`
+ - `bootstrap/cache`
+ - `public/uploads`
+
+**Note:** This access is likely controlled by the user/group of the PHP and/or web-server processes.
+
+Additionally, you may want to ensure read access the `.env` file is limited as much as possible, to just PHP/web-server process and any trusted users that may need to update it, since this file can often contain credentials and keys.
+
+### Example Permissions Approach
+
+This section provides an approach for setting permissions for your BookStack instance, which allows updating by the login user while providing the web-server with the required permissions.
+
+The below makes the following assumptions, **you will need to change these parts** of the command to make it work for you:
+
+- Your normal login user (That you may run updates with) is called `barry`.
+- Your BookStack install folder is located at `/var/www/bookstack`.
+- Your web-server/php user is called `www-data` (Default on Ubuntu systems).
+
+Lines starting with `#` are comments.
+
+```bash
+# Set the bookstack folders and files to be owned by the user barry and have the group www-data
+sudo chown -R barry:www-data /var/www/bookstack
+
+# Set all bookstack files and folders to be readable, writeable & executable by the user (barry) and
+# readable & executable by the group and everyone else
+sudo chmod -R 755 /var/www/bookstack
+
+# For the listed directories, grant the group (www-data) write-access
+sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
+
+# Limit the .env file to only be readable by the user and group, and only writable by the user.
+sudo chmod -R 640 /var/www/bookstack/.env
+```
```
2. `cd` into the application folder and run `composer install --no-dev`.
3. Copy the `.env.example` file to `.env` and fill with your own database and mail details.
-4. Ensure the `storage`, `bootstrap/cache` & `public/uploads` folders are writable by the web server.
+4. Ensure the `storage`, `bootstrap/cache` & `public/uploads` folders are writable by the web server ([More information here](/docs/admin/filesystem-permissions/)).
5. In the application root, Run `php artisan key:generate` to generate a unique application key.
6. If not using Apache or if `.htaccess` files are disabled you will have to create some URL rewrite rules as shown below.
7. Set the web root on your server to point to the BookStack `public` folder. This is done with the `root` setting on Nginx or the `DocumentRoot` setting on Apache.
+++ /dev/null
-+++
-title = "Bookstack Permissions Setup"
-description = "How to setup permissions to your Bookstack instance"
-date = "2023-02-27"
-type = "admin-doc"
-+++
-
-## BookStack Permission Setup
-
-This document provides an approach for setting permissions for your BookStack instance, which allows updating by the login user while providing the webserver with the required permissions.
-
-The below makes the following assumptions, **you will need to change these parts** of the command to make it work for you:
-
-- Your normal login user (That you may run updates with) is called `barry`.
-- Your bookstack folder is located at `/var/www/bookstack`.
-- Your webserver/php user called `www-data` (Default on Ubuntu systems).
-
-Lines starting with `#` are comments.
-
-```bash
-# Set the bookstack folders and files to be owned by the user barry and have the group www-data
-sudo chown -R barry:www-data /var/www/bookstack
-
-# Set all bookstack files and folders to be readable, writeable & executable by the user (barry) and
-# readable & executable by the group and everyone else
-sudo chmod -R 755 /var/www/bookstack
-
-# For the listed directories, grant the group (www-data) write-access
-sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
-
-# Limit the .env file to only be readable by the user and group, and only writable by the user.
-sudo chmod -R 640 /var/www/bookstack/.env
-```
If you are using Amazon S3 for file storage then access will depend on your S3 permission
settings. Unlike images, BookStack will not automatically attempt to make uploaded attachments
-publically accessible.
+publicly accessible.
+
+---
+
+### Filesystem Permissions
+
+It's usually a good idea to limit the file and folder access privileges for the user/group used to run the application PHP, which is typically the user/group for PHP or the running web-server processes. Limiting permissions can help avoid a range of potential vulnerability exploits.
+
+Details on required [filesystem permissions can be found here](/docs/admin/filesystem-permissions/).
---
php artisan view:clear
```
-Check the below list for the version you are updating to for any additional instructions.
+Check the below [Version Specific Instructions](#version-specific-instructions) list for the version you are updating to for any additional instructions.
+
+When running update commands, your command line user will need permission to handle the required files and folders in the BookStack installation folder. You can find more details about [required filesystem permissions here](/docs/admin/filesystem-permissions/).
---
<li><a href="/docs/admin/security">Security</a></li>
<li><a href="/docs/admin/multi-instance">Multiple Instances</a></li>
<li><a href="/docs/admin/subdirectory-setup">Subdirectory Setup</a></li>
- <li><a href="/docs/admin/permissions-setup">Permissions Setup</a></li>
</ul>
</div>
projects / website / commitdiff