starred/BookStack
1
0
Fork 0
mirror of https://github.com/BookStackApp/BookStack.git synced 2026-07-16 05:33:49 +03:00
Code Issues 784 Packages Projects Releases 25 Wiki Activity

S3 Storage (Digitalocean Spaces) compatibility issues #4217

New Issue
Closed
opened 2026-02-05 08:16:05 +03:00 by OVERLORD · 5 comments
OVERLORD commented 2026-02-05 08:16:05 +03:00
Owner
Copy Link

Originally created by @NianwenDan on GitHub (Sep 18, 2023).

Describe the Bug

Digitalocean Spaces is an S3-compatible storage. Compared to others, it is a budget solution based on download data usage and API usage.

However, the BookStack arises following an error message when I try to upload an image as my book cover:

League\Flysystem\UnableToCheckDirectoryExistence
Unable to check existence for: uploads/images/cover_book/2023-09/test.jpg

Here is my .env configuration related to the storage part:

# s3 Storage Type
STORAGE_TYPE=s3
STORAGE_S3_KEY=*********************
STORAGE_S3_SECRET=*********************
STORAGE_S3_BUCKET=&&&&&&&&
STORAGE_S3_ENDPOINT=https://&&&&&&&&.sfo3.digitaloceanspaces.com

Steps to Reproduce

Create Digital Ocean Spaces

  1. Log into the Digital Ocean
  2. Under MANAGE, click Spaces
  3. Click Create Spaces Bucket
  4. Set datacenter region in SFO3
  5. Disable Content Delivery Network
  6. Set a unique Spaces Bucket name
  7. Click Create a Spaces Bucket

Obtain API Key

  1. Log into the Digital Ocean
  2. Click API and choose Spaces Key
  3. Click Generate New Key
  4. Fill the KEY and SECRET into the .env configuration file

Upload an image

Debug mode should be activated before uploading:

# Debug Mode
APP_DEBUG=true
  1. Create a new book
  2. Select a random cover image (< 1Mb)
  3. Save book
  4. Error Message

Expected Behaviour

Files should be successfully uploaded to the Digitalocean Spaces.

Screenshots or Additional Context

PHP Version: 8.1.7

Browser Details

No response

Exact BookStack Version

v23.08.3

Originally created by @NianwenDan on GitHub (Sep 18, 2023). ### Describe the Bug [Digitalocean Spaces](https://www.digitalocean.com/products/spaces) is an S3-compatible storage. Compared to others, it is a budget solution based on download data usage and API usage. However, the BookStack arises following an error message when I try to upload an image as my book cover: ``` League\Flysystem\UnableToCheckDirectoryExistence Unable to check existence for: uploads/images/cover_book/2023-09/test.jpg ``` Here is my `.env` configuration related to the storage part: ``` # s3 Storage Type STORAGE_TYPE=s3 STORAGE_S3_KEY=********************* STORAGE_S3_SECRET=********************* STORAGE_S3_BUCKET=&&&&&&&& STORAGE_S3_ENDPOINT=https://&&&&&&&&.sfo3.digitaloceanspaces.com ``` ### Steps to Reproduce ## Create Digital Ocean Spaces 1. Log into the Digital Ocean 2. Under `MANAGE`, click `Spaces` 3. Click `Create Spaces Bucket` 4. Set datacenter region in `SFO3` 5. Disable Content Delivery Network 6. Set a unique Spaces Bucket name 7. Click `Create a Spaces Bucket` ## Obtain API Key 1. Log into the Digital Ocean 2. Click `API` and choose `Spaces Key` 3. Click `Generate New Key` 4. Fill the `KEY` and `SECRET` into the `.env` configuration file ## Upload an image Debug mode should be activated before uploading: ``` # Debug Mode APP_DEBUG=true ``` 1. Create a new book 2. Select a random cover image (< 1Mb) 3. Save book 4. Error Message ### Expected Behaviour Files should be successfully uploaded to the Digitalocean Spaces. ### Screenshots or Additional Context PHP Version: 8.1.7 ### Browser Details _No response_ ### Exact BookStack Version v23.08.3
OVERLORD added the 🐕 Support label 2026-02-05 08:16:05 +03:00
OVERLORD commented 2026-02-05 08:16:09 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Sep 18, 2023):

Hi @NianwenDan,
Unfortunately I cannot assure that every service that advertises "S3 compatibility" will be supported. Can ultimately come down to their implementation and level of support.

Looking at the error, this seems to be specifically failing on a ListObjectsV2 call, which DigitalOcean advertises to support, but I have not tested this live myself.
I get the feeling this may be related to permission control within spaces.

Does DigitalOcean offer permissions/controls on the "space", or key used for access, at all?
Worth looking for anything permission related that may affect "listing", or just accessing, files & folders.

@ssddanbrown commented on GitHub (Sep 18, 2023): Hi @NianwenDan, Unfortunately I cannot assure that every service that advertises "S3 compatibility" will be supported. Can ultimately come down to their implementation and level of support. Looking at the error, this seems to be specifically failing on a `ListObjectsV2` call, which [DigitalOcean advertises to support](https://docs.digitalocean.com/products/spaces/reference/s3-compatibility/), but I have not tested this live myself. I get the feeling this may be related to permission control within spaces. Does DigitalOcean offer permissions/controls on the "space", or key used for access, at all? Worth looking for anything permission related that may affect "listing", or just accessing, files & folders.
OVERLORD commented 2026-02-05 08:16:13 +03:00
Author
Owner
Copy Link

@NianwenDan commented on GitHub (Sep 18, 2023):

Hi @NianwenDan, Unfortunately I cannot assure that every service that advertises "S3 compatibility" will be supported. Can ultimately come down to their implementation and level of support.

Looking at the error, this seems to be specifically failing on a ListObjectsV2 call, which DigitalOcean advertises to support, but I have not tested this live myself. I get the feeling this may be related to permission control within spaces.

Does DigitalOcean offer permissions/controls on the "space", or key used for access, at all? Worth looking for anything permission related that may affect "listing", or just accessing, files & folders.

Hi @ssddanbrown,

DigitalOcean Spaces does offer permissions to list objects, and I tried to set it as Enable File Listing. Which should give permission to everyone who wants to list objects in the bucket. It didn't work.

image

I also noticed that "The Spaces API does not support list-objects-v2 pagination." is a known issue. According to https://docs.digitalocean.com/products/spaces/details/limits/

I am more concerned if DigitalOcean Spaces running a different API or return type resulting in this issue.

So far, I do not think it is a bug for BookStack upload module. But could DigitalOcean Spaces be supported in the future?

@NianwenDan commented on GitHub (Sep 18, 2023): > Hi @NianwenDan, Unfortunately I cannot assure that every service that advertises "S3 compatibility" will be supported. Can ultimately come down to their implementation and level of support. > > Looking at the error, this seems to be specifically failing on a `ListObjectsV2` call, which [DigitalOcean advertises to support](https://docs.digitalocean.com/products/spaces/reference/s3-compatibility/), but I have not tested this live myself. I get the feeling this may be related to permission control within spaces. > > Does DigitalOcean offer permissions/controls on the "space", or key used for access, at all? Worth looking for anything permission related that may affect "listing", or just accessing, files & folders. Hi @ssddanbrown, DigitalOcean Spaces does offer permissions to list objects, and I tried to set it as `Enable File Listing`. Which should give permission to everyone who wants to list objects in the bucket. It didn't work. <img width="907" alt="image" src="https://github.com/BookStackApp/BookStack/assets/74407127/5f8f2b37-651c-42ba-bb4e-c463e1836328"> I also noticed that "The Spaces API does not support list-objects-v2 pagination." is a known issue. According to [https://docs.digitalocean.com/products/spaces/details/limits/](https://docs.digitalocean.com/products/spaces/details/limits/) I am more concerned if DigitalOcean Spaces running a different API or return type resulting in this issue. So far, I do not think it is a bug for BookStack upload module. But could DigitalOcean Spaces be supported in the future?
OVERLORD commented 2026-02-05 08:16:17 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Sep 18, 2023):

@NianwenDan I've just been testing things against Digital Ocean spaces myself. All seems to work fine from my testing, but a few specific things to note:

  • Your STORAGE_S3_ENDPOINT should not include the bucket name. That will result in the error you experienced.
  • "File Listing" in Digital Ocean does not need to be enabled.
  • You will need to make the uploads/images folder within your space publicly accessible, while ideally keeping other paths inaccessible. Could't find a nice way to do this in-platform, but you could set S3 policies via the API. I used s3cmd to set the policy in my bucket for this:
s3cmd setpolicy policy.json s3://bookstack-testing

With policy.json being as per the below. You'd have to change bookstack-testing in this to match your bucket/space name.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::bookstack-testing/uploads/images/*"
            ]
        }
    ]
}

For reference, here are the relevant BookStack settings I used:

STORAGE_TYPE=s3
STORAGE_S3_KEY=DO00DQNxxxxxxxxxxxx
STORAGE_S3_SECRET=PB9y5sR8Q4wP0lmxxxxxxxxxxxxxxxxxxxxxxx
STORAGE_S3_BUCKET=bookstack-testing
STORAGE_S3_ENDPOINT=https://ams3.digitaloceanspaces.com
STORAGE_URL=https://bookstack-testing.ams3.digitaloceanspaces.com
@ssddanbrown commented on GitHub (Sep 18, 2023): @NianwenDan I've just been testing things against Digital Ocean spaces myself. All seems to work fine from my testing, but a few specific things to note: - Your `STORAGE_S3_ENDPOINT` should **not** include the bucket name. That will result in the error you experienced. - "File Listing" in Digital Ocean does **not** need to be enabled. - You will need to make the `uploads/images` folder within your space publicly accessible, while ideally keeping other paths inaccessible. Could't find a nice way to do this in-platform, but you could set S3 policies via the API. I used `s3cmd` to set the policy in my bucket for this: ```bash s3cmd setpolicy policy.json s3://bookstack-testing ``` With `policy.json` being as per the below. You'd have to change `bookstack-testing` in this to match your bucket/space name. ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "PublicReadGetObject", "Effect": "Allow", "Principal": "*", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::bookstack-testing/uploads/images/*" ] } ] } ``` For reference, here are the relevant BookStack settings I used: ```bash STORAGE_TYPE=s3 STORAGE_S3_KEY=DO00DQNxxxxxxxxxxxx STORAGE_S3_SECRET=PB9y5sR8Q4wP0lmxxxxxxxxxxxxxxxxxxxxxxx STORAGE_S3_BUCKET=bookstack-testing STORAGE_S3_ENDPOINT=https://ams3.digitaloceanspaces.com STORAGE_URL=https://bookstack-testing.ams3.digitaloceanspaces.com ```
OVERLORD commented 2026-02-05 08:16:20 +03:00
Author
Owner
Copy Link

@NianwenDan commented on GitHub (Sep 18, 2023):

Hi @ssddanbrown,

I am sorry I didn't read Digital Ocean Spaces API documentation before.

That method did work for me.

Also, this issue tends to be more focused on how to set up the configuration file correctly, specifically for DigitalOcean Spaces. It would be better to change the tag from Bug to Support, and mark it closed.

Thanks for your time to help me out again!

@NianwenDan commented on GitHub (Sep 18, 2023): Hi @ssddanbrown, I am sorry I didn't read Digital Ocean Spaces API documentation before. That method did work for me. Also, this issue tends to be more focused on how to set up the configuration file correctly, specifically for DigitalOcean Spaces. It would be better to change the tag from `Bug` to `Support`, and mark it closed. Thanks for your time to help me out again!
OVERLORD commented 2026-02-05 08:16:24 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Sep 18, 2023):

Happy you could get things working! Will therefore close this off.
Also, thanks for the sponsorship!

@ssddanbrown commented on GitHub (Sep 18, 2023): Happy you could get things working! Will therefore close this off. Also, thanks for the sponsorship!
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
🎨 Design
📖 Docs Update
🐛 Bug
🐛 Bug
:cat2:🐈 Possible duplicate
💿 Database
☕ Open to discussion
💻 Front-End
🐕 Support
🚪 Authentication
🌍 Translations
🔌 API Task
🏭 Back-End
⛲ Upstream
🔨 Feature Request
🛠️ Enhancement
🛠️ Enhancement
🛠️ Enhancement
❤️ Happy feedback
🔒 Security
🔍 Pending Validation
💆 UX
📝 WYSIWYG Editor
🌔 Out of scope
🔩 API Request
:octocat: Admin/Meta
🖌️ View Customization
❓ Question
🚀 Priority
🛡️ Blocked
🚚 Export System
♿ A11y
🔧 Maintenance
> Markdown Editor
pull-request
Mirrored from GitHub Pull Request
No Label 🐕 Support
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
OVERLORD
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/BookStack#4217
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?