Configuring File Upload

Migrating to “Secure” Images

Back-up your BookStack instance before attempting any migration

If you are migrating to the STORAGE_TYPE=local_secure or STORAGE_TYPE=local_secure_restricted options, with existing images, you will need to move all content from your previous image storage location (see above) to the storage/uploads/images folder within your BookStack instance.

Do not simply copy and leave content in the public/uploads/images as those images will still be publicly accessible. After doing this migration you may have to clean-up and re-upload any ‘App Icon’ images, found in settings, since these need to remain publicly accessible.

Changing Upload Limits

By default, a lot of server software has strict limits on upload sizes which causes errors when users upload new content. BookStack enforces its own limit but there may also be limits configured as part of PHP and your web sever software. If you run into problems with upload size limits follow the below details for BookStack, PHP and whichever web server you use.

BookStack

The upload limit in BookStack is configured through an option in your .env file. Find or add the follow option then configure to your requirements.

1
2
3

# File Upload Limit
# Maximum file size, in megabytes, that can be uploaded to the system.
FILE_UPLOAD_SIZE_LIMIT=50

PHP

PHP has two main variables which effect upload limits. Find your php.ini file and look for the following variables:

• post_max_size
• upload_max_filesize

If the values of these variables are low increase them to something sensible that’s not too high to cause issues. Unless you need something higher 10MB is a sensible value to enter for these values:

1
2

post_max_size = 10M
upload_max_filesize = 10M

If wanting to upload files over 128MB, you may also need to adjust your PHP memory limit like so:

1

memory_limit = 256M

After updating these values ensure you restart your webserver and also PHP if using PHP-FPM or something similar.

NGINX

By default NGINX has a limit of 1MB on file uploads. To change this you will need to set the client_max_body_size variable. You can do this either in the http block in your nginx.conf file or in the server block set up for BookStack. Here’s an example of increasing the limit to 100MB in the http block:

1
2
3
4
5
6

http {
	#...
        client_max_body_size 100m;
        client_body_timeout 120s; # Default is 60, May need to be increased for very large uploads
	#...
}

As per the example above, If you are expecting upload very large files where upload times will exceed 60 seconds you will also need to add the client_body_timeout variable with a large value.

After updating you NGINX configuration don’t forget to restart NGINX. You can test the configuration beforehand with nginx -t.

Apache

Apache does not have any built-in limits which you will need to change but something to note is that if you are using apache and mod_php with .htaccess files enabled you may be able to set the above PHP variables in your .htaccess file like so:

1
2

php_value upload_max_filesize 10M
php_value post_max_size 10M