[docs] revamp "Configuring S3" (#4821)

PR is about making improvements to the "Configuring S3" Document. Making
sure to staying with the principles of the previous doc just making
improvements in the explanation.

Also added a diagram, will keep it updated as I develop better
understanding of the whole Client, Museum and S3 Relation :)

docs/docs/.vitepress/config.ts

@@ -8,6 +8,13 @@ export default defineConfig({
     head: [["link", { rel: "icon", type: "image/png", href: "/favicon.png" }]],
     cleanUrls: true,
     ignoreDeadLinks: "localhostLinks",
+    vite: {
+      build: {
+        rollupOptions: {
+          external: ['client-museum-s3.png'] // Added to handle static asset import
+        }
+      }
+    },
     themeConfig: {
         // We use the default theme (with some CSS color overrides). This
         // themeConfig block can be used to further customize the default theme.

docs/docs/.vitepress/sidebar.ts

@@ -247,15 +247,6 @@ export const sidebar = [
                         text: "Hosting the web app",
                         link: "/self-hosting/guides/web-app",
                     },
-                    {
-                        text: "Administering your server",
-                        link: "/self-hosting/guides/admin",
-                    },
-
-                    {
-                        text: "Mobile build",
-                        link: "/self-hosting/guides/mobile-build",
-                    },
                     {
                         text: "Configuring S3",
                         link: "/self-hosting/guides/configuring-s3",
@@ -276,6 +267,15 @@ export const sidebar = [
                         text: "Configure CLI for Self Hosted Instance",
                         link: "/self-hosting/guides/selfhost-cli",
                     },
+                    {
+                        text: "Administering your server",
+                        link: "/self-hosting/guides/admin",
+                    },
+
+                    {
+                        text: "Mobile build",
+                        link: "/self-hosting/guides/mobile-build",
+                    },
                 ],
             },
             {

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

@@ -5,7 +5,9 @@ description:
     from outside localhost
 ---
 
-# Configuring S3
+# Components of the Architecture
+
+![Client, Museum, S3](/client-museum-s3.png)
 
 There are three components involved in uploading:
 
@@ -24,6 +26,8 @@ interaction goes something like this:
 The upshot of this is that _both_ the client and museum should be able to reach
 your S3 bucket.
 
+## Configuring S3 
+
 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
@@ -32,61 +36,64 @@ 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 documentation for
 > the `s3` object in
 > [configurations/local.yaml](https://github.com/ente-io/ente/blob/main/server/configurations/local.yaml).
 
 By default, you only need to configure the endpoint for the first bucket.
 
-> [!NOTE]
->
-> If you're wondering why there are 3 buckets - that's because our production
-> instance uses these to perform replication.
->
-> However, in a self hosted setup replication is off by default (you can turn it
-> on if you want). When replication is turned off, only the first bucket (it
-> must be named `b2-eu-cen`) is used, and you can ignore the other two. Use the
-> `hot_bucket` option if you'd like to set one of the other predefined buckets
-> as 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 docker compose file is shipped with MinIO as the Self Hosted S3 Compatible Storage. 
+By default, MinIO server is served on `localhost:3200` and the MinIO UI on 
+`localhost:3201`. 
+For example, in a localhost network situation, the way this 
+connection works is, Museum (`1`) and MinIO (`2`) run on the same docker network and 
+the web app (`3`) which will also be hosted on the localhost. This enables all the 
+three components of the setup being able to communicate with each other seamlessly.
 
 The same principle applies if you're deploying to your custom domain.
 
+## Replication 
+
+If you're wondering why there are 3 buckets on MinIO UI - that's because our 
+production instance uses these to perform [replication](https://ente.io/reliability/).
+
+In a self hosted Ente Instance replication is turned off by default.
+When replication is turned off, only the first bucket (`b2-eu-cen`) is used, 
+and you can ignore the other two. Use the `s3.hot_storage.primary` option 
+if you'd like to set one of the other predefined buckets as the primary bucket.
+
+> [!IMPORTANT]
+> As of now, Replication works only if all the 3 storage type 
+> needs are fulfilled (1 Hot, 1 Cold and 1 Glacier Storage).
+>
+> [Reference](https://github.com/ente-io/ente/discussions/3167#discussioncomment-10585970)
+
+## SSL Configuration 
+
 > [!NOTE]
 >
 > If you need to configure SSL, for example if you're running over the internet,
 > you'll need to turn off `s3.are_local_buckets` (which disables SSL in the
 > default starter compose template).
 >
-> Disabling `s3.are_local_buckets` also switches to the subdomain style URLs for
-> the buckets. However, not all S3 providers support these, in particular, minio
-> does not work with these in default configuration. So in such cases you'll
-> also need to then enable `s3.use_path_style_urls`.
 
-To summarize:
+Disabling `s3.are_local_buckets` also switches to the subdomain style URLs for
+the buckets. However, not all S3 providers support these, in particular, minio
+does not work with these in default configuration. So in such cases you'll
+also need to then enable `s3.use_path_style_urls`.
+
+## Summary
 
 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.
 
-### Example
+#### Example
 
 An example `museum.yaml` when you're trying to connect to museum running on your
 computer from your phone on the same WiFi network:
 
-```
+```yaml
 s3:
     are_local_buckets: true
     b2-eu-cen:
@@ -97,6 +104,20 @@ s3:
         bucket: b2-eu-cen
 ```
 
+## FAE (Frequently Answered Errors)
+
+Here are some Frequently Answered Errors from the Community Chat with the reasoning
+for a particular error and its potential fix. 
+
+In most situations, the problem turns out to be some minute mistakes or misconfigurations 
+on the users end and that turns out to be the bottleneck of the whole problem. 
+Please make sure to `reverse_proxy` Museum to a domain as well as check your S3 
+Credentials and whole config for any minor mis-configurations.
+
+It is also suggested that the user setups Bucket CORS on MinIO or any external
+S3 Bucket they are connecting to. To setup Bucket CORS, help yourself by upload
+[this](https://help.ente.io/self-hosting/guides/external-s3#_5-fix-potential-cors-issue-with-your-bucket).
+
 ### 403 Forbidden
 
 If museum (`2`) is able to make a network connection to your S3 bucket (`3`) but
@@ -108,11 +129,24 @@ corresponding object exists in the S3 bucket.
 To fix these, you should ensure the following:
 
 1.  The bucket CORS rules do not allow museum to access these objects.
-
-    > For uploading files from the browser, you will need to currently set
-    > allowedOrigins to "\*", and allow the "X-Auth-Token", "X-Client-Package"
-    > headers configuration too.
-    > [Here is an example of a working configuration](https://github.com/ente-io/ente/discussions/1764#discussioncomment-9478204).
+    - For uploading files from the browser, you will need to currently set
+    allowedOrigins to "\*", and allow the "X-Auth-Token", "X-Client-Package"
+    headers configuration too.
+    [Here is an example of a working configuration](https://github.com/ente-io/ente/discussions/1764#discussioncomment-9478204).
 
 2.  The credentials are not being picked up (you might be setting the correct
     creds, but not in the place where museum picks them from).
+
+### Mismatch in File Size 
+
+The "Mismatch in File Size" error mostly occurs in a situation where the client (`1`) 
+is re-uploading a file which is already in the bucket with a different File Size. The 
+reason for re-upload could be anything including Network issue, sudden killing of app
+before the upload is complete and etc. 
+
+This is also one of Museums (`2`) Validation Checks for the size of file being 
+re-uploaded from the client to the size of the file which is already 
+uploaded to the S3 Bucket.
+
+In most case, it is very unlikely that this error could be a cause of some mistake in 
+the configuration or Browser/Bucket CORS.