Clearer explanation of Amazon S3 setup in .env #928

New Issue

OVERLORD · 2026-02-04T22:58:27+03:00

OVERLORD commented

2026-02-04 22:58:27 +03:00

Originally created by @willc on GitHub (Nov 29, 2018).

Some documentation/comments in the .env file about what to edit when setting up S3 storage would be helpful. The current default storage settings are:

# Storage
STORAGE_TYPE=local
# Amazon S3 Config
STORAGE_S3_KEY=false
STORAGE_S3_SECRET=false
STORAGE_S3_REGION=false
STORAGE_S3_BUCKET=false
# Storage URL
# Used to prefix image urls for when using custom domains/cdns
STORAGE_URL=false

I understand what to enter for the S3 parts (KEY, SECRET, REGION, BUCKET), but I am not sure if these need to be changed, and if they do, to what:

STORAGE_TYPE=local
STORAGE_URL=false

Hopefully this will prevent users from not knowing how to set this up, as there doesn't seem to be any documentation about it now. Thus, I am getting image upload errors like "An error occurred uploading the image," and don't know how to resolve.

Originally created by @willc on GitHub (Nov 29, 2018). Some documentation/comments in the .env file about what to edit when setting up S3 storage would be helpful. The current default storage settings are: ``` # Storage STORAGE_TYPE=local # Amazon S3 Config STORAGE_S3_KEY=false STORAGE_S3_SECRET=false STORAGE_S3_REGION=false STORAGE_S3_BUCKET=false # Storage URL # Used to prefix image urls for when using custom domains/cdns STORAGE_URL=false ``` I understand what to enter for the S3 parts (KEY, SECRET, REGION, BUCKET), but I am not sure if these need to be changed, and if they do, to what: ``` STORAGE_TYPE=local STORAGE_URL=false ``` Hopefully this will prevent users from not knowing how to set this up, as there doesn't seem to be any documentation about it now. Thus, I am getting image upload errors like "An error occurred uploading the image," and don't know how to resolve. ![image](https://user-images.githubusercontent.com/23823/49190353-fa24b900-f33f-11e8-940a-5602eafa226c.png)

OVERLORD added the 📖 Docs Update label 2026-02-04 22:58:27 +03:00

OVERLORD closed this issue

2026-02-04 22:58:30 +03:00

OVERLORD commented

2026-02-04 22:58:35 +03:00

@ssddanbrown commented on GitHub (Nov 29, 2018):

Hi @willc,

STORAGE_TYPE tells bookstack what storage system to use, If you want to use S3 then set STORAGE_TYPE=s3.

STORAGE_URL is the base URL to use for assets, So set to your base s3 instance URL or a custom one if you have a custom (sub)domain pointing to s3.

I've marked this to be added to the docs.

@ssddanbrown commented on GitHub (Nov 29, 2018): Hi @willc, `STORAGE_TYPE` tells bookstack what storage system to use, If you want to use S3 then set `STORAGE_TYPE=s3`. `STORAGE_URL` is the base URL to use for assets, So set to your base s3 instance URL or a custom one if you have a custom (sub)domain pointing to s3. I've marked this to be added to the docs.

OVERLORD commented

2026-02-04 22:58:40 +03:00

@willc commented on GitHub (Nov 29, 2018):

Thanks @ssddanbrown, that makes sense. Is there a place where connection failures get logged? Still getting the same error, though my setting all seem to be correct based on the info above.

Digging through apache logs and other logs in /var/log didn't turn up anything.

@willc commented on GitHub (Nov 29, 2018): Thanks @ssddanbrown, that makes sense. Is there a place where connection failures get logged? Still getting the same error, though my setting all seem to be correct based on the info above. Digging through apache logs and other logs in /var/log didn't turn up anything.

OVERLORD commented

2026-02-04 22:58:48 +03:00

@ssddanbrown commented on GitHub (Nov 29, 2018):

@willc There's details on debugging in the docs here. It makes it more difficult that image uploads are background requests but you can check the application log (Detailed on that page).

Been a while since it played about with the s3 image system so can't remember how much detail you get.

@ssddanbrown commented on GitHub (Nov 29, 2018): @willc There's details on debugging [in the docs here](https://www.bookstackapp.com/docs/admin/debugging/). It makes it more difficult that image uploads are background requests but you can check the application log (Detailed on that page). Been a while since it played about with the s3 image system so can't remember how much detail you get.

OVERLORD commented

2026-02-04 22:58:51 +03:00

@willc commented on GitHub (Nov 29, 2018):

Thanks, nothing was revealed in debug or the laravel logs, which led me to believe something was wrong with my S3 setup, and it was. Got it all working now.

@willc commented on GitHub (Nov 29, 2018): Thanks, nothing was revealed in debug or the laravel logs, which led me to believe something was wrong with my S3 setup, and it was. Got it all working now.

OVERLORD commented

2026-02-04 22:59:03 +03:00

@ssddanbrown commented on GitHub (May 18, 2019):

Details of s3 based image storage was added back in Jan, Therefore I'll close this.
Documentation for reference:
https://www.bookstackapp.com/docs/admin/upload-config/#s3

@ssddanbrown commented on GitHub (May 18, 2019): Details of s3 based image storage was added back in Jan, Therefore I'll close this. Documentation for reference: https://www.bookstackapp.com/docs/admin/upload-config/#s3

OVERLORD referenced this issue

2026-02-05 03:29:25 +03:00

Markdown - Linebreaks II #2262

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#928