[docs] Expand on the S3 configuration (#1697)

docs/docs/.vitepress/sidebar.ts

@@ -201,6 +201,10 @@ export const sidebar = [
                         text: "System requirements",
                         link: "/self-hosting/guides/system-requirements",
                     },
+                    {
+                        text: "Configuring S3",
+                        link: "/self-hosting/guides/configuring-s3",
+                    },
                     {
                         text: "Using external S3",
                         link: "/self-hosting/guides/external-s3",

docs/docs/photos/features/cast/index.md

@@ -1,6 +1,7 @@
 ---
 title: Cast
-description: Casting your photos on to a large screen or a TV or a Chromecast device
+description:
+    Casting your photos on to a large screen or a TV or a Chromecast device
 ---
 
 # Cast

docs/docs/photos/troubleshooting/desktop-install/index.md

@@ -23,10 +23,11 @@ It is possible that the exact path might be different on your machine. Briefly,
 what we need to do is create `libz.so` as an alias for `libz.so.1`. For more
 details, see the following bugs in upstream repositories:
 
-* libz.so cannot open shared object file on ARM64 -
-  [/github.com/AppImage/AppImageKit/issues/1092](https://github.com/AppImage/AppImageKit/issues/1092)
+-   libz.so cannot open shared object file on ARM64 -
+    [/github.com/AppImage/AppImageKit/issues/1092](https://github.com/AppImage/AppImageKit/issues/1092)
 
-* libz.so: cannot open shared object file with Ubuntu arm64 - [github.com/electron-userland/electron-builder/issues/7835](https://github.com/electron-userland/electron-builder/issues/7835)
+-   libz.so: cannot open shared object file with Ubuntu arm64 -
+    [github.com/electron-userland/electron-builder/issues/7835](https://github.com/electron-userland/electron-builder/issues/7835)
 
 ## AppImage says it requires FUSE
 

docs/docs/self-hosting/guides/configuring-s3.md

@@ -0,0 +1,58 @@
+---
+title: Configuring S3 buckets
+description: Fixing upload errors when trying to self host Ente
+---
+
+# Configuring S3
+
+There are three components involved in uploading:
+
+1.  The client (e.g. the web app or the mobile app)
+2.  Ente's server (museum)
+3.  The S3-compatible object storage (e.g. minio in the default starter)
+
+For the uploads to work, all three of them need to be able to reach each other.
+This is because the client uploads directly to the object storage. The
+interaction goes something like this:
+
+1.  Client wants to upload, it asks museum where it should upload to.
+2.  Museum creates pre-signed URLs for the S3 bucket that was configured.
+3.  Client directly uploads to the S3 buckets these URLs.
+
+The upshot of this is that _both_ the client and museum should be able to reach
+your S3 bucket.
+
+The URL for the S3 bucket is configured in
+[scripts/compose/credentials.yaml](https://github.com/ente-io/ente/blob/main/server/scripts/compose/credentials.yaml#L10).
+You can edit this file directly when testing, though it is just simpler and more
+robust to create a `museum.yaml` (in the same folder as the Docker compose file)
+and put your custom configuration there (in your case, you can put an entire
+`s3` config object in your `museum.yaml`).
+
+> [!TIP]
+>
+> For more details about these configuration objects, see the documentaion for
+> the `s3` object in
+> [configurations/local.yaml](https://github.com/ente-io/ente/blob/main/server/configurations/local.yaml).
+
+By default, replication is turned off so unless you've enabled you only need to
+configure the endpoint for the first bucket.
+
+The `endpoint` for the first bucket in the starter `credentials.yaml` is
+`localhost:3200`. The way this works then is that both museum (`2`) and minio
+(`3`) are running within the same Docker compose cluster, so are able to reach
+each other. If at this point we were to run the web app (`1`) on localhost (say
+using `yarn dev:photos`), it would also run on localhost and thus would be able
+to reach `3`.
+
+If you were to try and connect from a mobile app, this would not work since
+`localhost:3200` would not resolve on your mobile. So you'll need to modify this
+endpoint to a value, say `yourserverip:3200`, so that the mobile app can also
+reach it.
+
+The same principle applies if you're deploying to your custom domain. To
+summarize:
+
+Set the S3 bucket `endpoint` in `credentials.yaml` to a `yourserverip:3200` or
+some such IP/hostname that accessible from both where you are running the Ente
+clients (e.g. the mobile app) and also from within the Docker compose cluster.

docs/docs/self-hosting/guides/index.md

@@ -16,5 +16,8 @@ See the sidebar for existing guides. In particular:
 -   For various admin related tasks, e.g. increasing the storage quota on your
     self hosted instance, see [administering your custom server](admin).
 
--   For self hosting both the server and web app using external S3 buckets for
-    object storage, see [using external S3](external-s3).
+-   For configuring your S3 buckets to get the object storage to work from your
+    mobile device or for fixing an upload errors, see
+    [configuring S3](configuring-s3). There is also a longer
+    [community contributed guide](external-s3) for a more self hosted setup of
+    both the server and web app using external S3 buckets for object storage.

docs/docs/self-hosting/troubleshooting/uploads.md

@@ -5,9 +5,9 @@ description: Fixing upload errors when trying to self host Ente
 
 # Uploads failing
 
-If uploads to your self-hosted server are failing, make sure that
-`credentials.yaml` has `yourserverip:3200` for all three minio locations.
+If uploads to your minio are failing, you need to ensure that you've configured
+the S3 bucket `endpoint` in `credentials.yaml` (or `museum.yaml`) to, say,
+`yourserverip:3200`. This can be any host or port, it just need to be a value
+that is reachable from both your client and from museum.
 
-By default it is `localhost:3200`, and it needs to be changed to an IP that is
-accessible from both where you are running the Ente clients (e.g. the mobile
-app) and also from within the Docker compose cluster.
+For more details, see [configuring-s3](/self-hosting/guides/configuring-s3).