Merge pull request #57 from prose-im/master

valeriansaliou · web-flow · commit 0ebb7a158d3e · 2025-06-22T13:10:56.000+02:00
Bumps
diff --git a/config/common.json b/config/common.json
@@ -70,13 +70,28 @@
     }
   },
 
+  "colors" : {
+    "changes" : {
+      "groups" : {
+        "pod" : "#d34040",
+        "app" : "#dc9b37"
+      }
+    }
+  },
+
   "texts" : {
     "home" : {
       "title" : "Welcome to the Prose Technical Docs",
-      "label" : "Guides how to start using Prose and setup your own Prose Pod server."
+      "label" : "How to setup your own Prose Pod server. For Prose server admins."
     },
 
     "changes" : {
+      "groups" : {
+        "pod"   : "Pod",
+        "app"   : "App",
+        "other" : "Other"
+      },
+
       "titles" : {
         "feed"   : "Prose Platform Changes",
         "latest" : "Latest Platform Changes",
@@ -161,7 +176,7 @@
   "actions" : {
     "home" : [
       {
-        "route" : ["guides", "start"],
+        "route" : ["guides", "basics", "quickstart"],
         "label" : "Get Started with Prose"
       }
     ]
@@ -185,13 +200,13 @@
 
         "actions"     : [
           {
-            "route" : ["guides", "operating"],
-            "label" : "Server Setup"
+            "route" : ["guides", "dashboard"],
+            "label" : "Use Dashboard"
           },
 
           {
-            "route" : ["guides", "others", "security"],
-            "label" : "Security"
+            "route" : ["guides", "operating"],
+            "label" : "Operate a Pod"
           }
         ]
       },
diff --git a/src/data/changes/2022.json b/src/data/changes/2022.json
diff --git a/src/data/changes/2025.json b/src/data/changes/2025.json
@@ -0,0 +1,8 @@
+[
+  {
+    "group" : "app",
+    "type"  : "update",
+    "date"  : "2025-06-22",
+    "text"  : "Beta versions of the macOS and Windows application have been released."
+  }
+]
diff --git a/src/data/guides/basics/download/index.md b/src/data/guides/basics/download/index.md
@@ -4,24 +4,30 @@ UPDATED: 2025-05-28
 
 ## Using our “Downloads” page
 
-Go to [prose.org/downloads](https://prose.org/downloads) and .
+⭐️ _This is the preferred way to install Prose._
+
+Go to [our downloads page](https://prose.org/downloads) and get the Prose application for your platform (macOS or Windows).
+
+---
 
 ## Using a package manager
 
-### Homebrew
+### 1. Homebrew (macOS)
 
-To install:
+**To install the Prose app:**
 
 ```bash
 brew install --cask prose-im/tap/prose
 ```
 
-Then to update:
+**Then to update it:**
 
 ```bash
 brew upgrade --cask prose-im/tap/prose
 ```
 
-### Other package managers
+### 2. Other package managers
+
+We don’t plan on maintaining packages for every package manager ourselves, but if you maintain a package and would like it to be listed here, feel free to create an issue on [prose-im/prose-docs](https://github.com/prose-im/prose-docs/issues) or reach out to [our support team](https://prose.org/contact/) if you don’t have a GitHub account.
 
-We don’t plan on maintaining packages for every package manager ourselves, but if you maintain a package and would like it to be listed here, feel free to create an issue on [prose-im/prose-docs](https://github.com/prose-im/prose-docs/issues) or reach out to [our support team](#crisp-chat-open) if you don’t have a GitHub account. We will then edit this page to mention your community-maintained package.
+We will then edit this page to mention your community-maintained package.
diff --git a/src/data/guides/basics/index.md b/src/data/guides/basics/index.md
@@ -2,6 +2,8 @@ TITLE: Basics
 INDEX: 1
 UPDATED: 2025-05-31
 
+👋 **Welcome to the Prose Technical docs!** This quickstart guide will help you setup a Prose server, and get Prose apps to run in a matter of minutes. Please follow the guides below in order to get started:
+
 + Navigation
   | Quickstart: Setup Prose in a matter of minutes. -> ./quickstart/
   | Download Prose: Download the Prose app to start chatting. -> ./download/
diff --git a/src/data/guides/basics/quickstart/index.md b/src/data/guides/basics/quickstart/index.md
@@ -6,14 +6,16 @@ UPDATED: 2025-05-31
 
 ## Creating a Prose workspace
 
-To create a Prose workspace, the easiest solution is to use our Cloud-hosted service. It is fully managed (uptime & updates) and allows for unlimited members. If you want to deploy Prose on your own premises, you can use the Community version, but beware that it has a 100 members limit. For more information, head over to [our Pricing page](https://prose.org/pricing/ "Pricing | Prose IM").
+To create a Prose workspace, the easiest solution is to use our Cloud-hosted service. It is fully managed (uptime & updates) and allows for unlimited members. If you want to deploy Prose on your own premises, you can use the Community version, but beware that it has a 20 members limit. For more information, head over to [our Pricing page](https://prose.org/pricing/ "Pricing | Prose IM").
 
 !!! TODO: @valerian Is there a way to change “Read” in the navigation links and make it open in an external tab?
 
 + Navigation
   | Prose Cloud: The easiest way to use Prose in your company. -> https://prose.org/cloud/signup/
   | Self-hosted (Community): Want to host a Prose Pod youself? Read this guide. -> /guides/operating/deploy/
 
+---
+
 ## Initializing your workspace
 
 !!! TODO: @valerian Where does the user get the URL to their Dashboard in the Cloud version?
@@ -28,48 +30,30 @@ The first screen will ask you to choose a domain for your instant messaging serv
 
 ! Prose can co-exist with your email and website **on the same domain**, you don’t need a subdomain for it to work properly.
 
-<details>
-  <summary>Click to show an example screenshot</summary>
-
 $[Workspace domain initialization screen](![Workspace initialization screen, workspace domain](init-domain-fresh.png))
 
-</details>
-
 ### Workspace name
 
 After that, you will be prompted for a workspace name. It will be used on **Prose apps** to identify your workspace. We recommend using your **organization name**.
 
-<details>
-  <summary>Click to show an example screenshot</summary>
-
 $[Workspace name initialization screen](![Workspace initialization screen, workspace name](init-name-fresh.png))
 
-</details>
-
 ### First admin account
 
 Finally, you will be asked for information about the first account you need to create: the initial workspace administrator. Using this account, you will be able to log into the Dashboard to invite users and configure your workspace.
 
-<details>
-  <summary>Click to show an example screenshot</summary>
-
 $[Admin account creation screen](![Workspace initialization screen, admin account](init-admin-fresh.png))
 
-</details>
+---
 
 ## Configuring DNS records
 
 Before you can start using your Prose workspace, you will have to configure DNS records to link it to your domain.
 
 We provide you all the DNS records you need to configure. To find them, navigate to “Advanced Settings” > “Network Setup” then under “Network Setup Tools” click “Show DNS instructions…”.
 
-<details>
-  <summary>Click to show an example screenshot</summary>
-
 $[DNS setup instructions screen](![DNS setup instructions screen](dns-records-demo.png))
 
-</details>
-
 <!-- FIX: Without this line break, the folowwing paragraph is too close to the details tag. -->
 <br/>
 
@@ -87,17 +71,14 @@ Once you have created all DNS records, close the “DNS setup instructions” pa
 
 You should then see a screen that runs different network configuration checks and shows what is still misconfigured.
 
-<details>
-  <summary>Click to show an example screenshot</summary>
-
 $[Network configuration checker screen](![Network configuration checker screen](network-checks-demo.png))
 
-</details>
-
 !! <p>If failed, network checks retry after 5 seconds (or whetever your [`default_retry_interval` configuration](/references/pod-config/#general-settings) is). This means you can leave the pane open, change some configuration and come back to see if it is now fixed.</p><p>However, note that network configuration usually takes some time to propagate due to multiple layers of caching in networks. The Prose Pod API tries to run DNS checks directly, but you might still have to wait for clients to connect properly.</p><p>Also beware that network checks will stop retying after 5 minutes, to avoid useless retries if you kept the pane open in another we browser tab. In this situation, you can hit the restart button at the top of the pane or close and reopen the pane to reset this timer.</p>
 
 Once all network checks have passed, your Prose workspace is ready to be used 🥳
 
+---
+
 ## Inviting the first member
 
 After you’ve [configured your DNS records](#configuring-dns-records) and [checked that they are correctly configured](#ensuring-your-network-configuration-is-correct), it’s now time to invite your first colleague!
@@ -106,12 +87,9 @@ To do so, open “Team Members” > “Members & Invites” then click “Add a
 
 !!! **Attention:** The username you choose when creating the invitation is definitive. You will not be able to change it after the account is created.
 
-<details>
-  <summary>Click to show an example screenshot</summary>
-
 $[“Invite a team member” screen](![“Invite a team member” screen](invite-member-fresh.png))
 
-</details>
+---
 
 ## Next steps
 
diff --git a/src/data/guides/dashboard/index.md b/src/data/guides/dashboard/index.md
@@ -2,9 +2,11 @@ TITLE: Using the Dashboard
 INDEX: 2
 UPDATED: 2025-05-28
 
+This section contains tutorials on how to use your Prose Pod dashboard to manage your Pod.
+
 !!! 🚧 This guide is still a work-in-progress.
 
 + Navigation
-  | Inviting members: -> ./invitations/
-  | Configuring your server: -> ./server-config/
-  | Customizing your workspace: -> ./workspace-customization/
+  | Inviting members: Learn how to invite members to your Prose Pod. -> ./invitations/
+  | Configuring your server: Configure your server and tune it to your needs. -> ./server-config/
+  | Customizing your workspace: Customize your workspace with your brand. -> ./workspace-customization/
diff --git a/src/data/guides/index.md b/src/data/guides/index.md
@@ -10,4 +10,4 @@ UPDATED: 2025-05-22
   | Server Setup: Guides to help you setup your own Prose server. -> ./operating/
   | Other guides: Other guides are classified there. -> ./others/
 
-! If you have any technical question while setting up your Prose server, feel free to [chat with our support team](#crisp-chat-open). Our technical support team will gladly help you fix any issue you encounter.
+! If you have any technical question while setting up your Prose server, feel free to [chat with our support team](https://prose.org/contact/). Our technical support team will gladly help you fix any issue you encounter.
diff --git a/src/data/guides/operating/debug/index.md b/src/data/guides/operating/debug/index.md
@@ -9,12 +9,14 @@ When something isn’t working correctly in your Prose Pod, your first source o
 - [Prose apps (client side)](#debugging-prose-apps-client-side)
 - [Prose apps (server side)](#debugging-prose-apps-server-side)
 
-! If you can’t find the source of a problem after reading this guide, feel free to [contact our technical support team](#crisp-chat-open) which will gladly help you identify the issue.
+! If you can’t find the source of a problem after reading this guide, feel free to [contact our technical support team](https://prose.org/contact/) which will gladly help you identify the issue.
 
 ## Debugging the Dashboard (client side)
 
 In your web browser, open the developer console and look for errors or warnings.
 
+---
+
 ## Debugging the Dashboard (server side)
 
 If your issue happens when using the Dashboard but the developer console shows nothing, checking the Pod API logs should help you. Depending on how you started your Prose Pod, you can see it using `docker compose logs`, `journalctl` or some other utility.
@@ -37,12 +39,16 @@ If you can’t easily change this configuration file and would prefer using envi
 
 If you’re seeing timing issues, you might want to check logs in a telemetry console instead of a terminal. To enable telemetry, read [our “Telemetry” guide](/guides/operating/telemetry/).
 
+---
+
 ## Debugging Prose apps (client side)
 
 On macOS, find logs at `~/Library/Logs/org.prose.app-web/Prose.log`.
 
 In your web browser, open the developer console.
 
+---
+
 ## Debugging Prose apps (server side)
 
 If your issue happens when using the Prose apps but client logs show nothing, only the Pod Server logs can help you. Depending on how you started your Prose Pod, you can see it using `docker compose logs`, `journalctl` or some other utility.
diff --git a/src/data/guides/operating/deploy/index.md b/src/data/guides/operating/deploy/index.md
@@ -44,6 +44,8 @@ And here are all the files you need to create and maintain:
 - `/etc/prose/prose.env`: If using our Compose file (see [Example: Compose](#example-compose) later), this is where you can configure environment variables for your Prose Pod.
 - `/etc/prosody/certs/*`: SSL certificates for your domain.
 
+---
+
 ## Deployment steps
 
 ### Step 0: A helper variable
@@ -163,7 +165,7 @@ Once done, **edit the file to replace all placeholders** with your company infor
 
 To run a Prose Pod on your premises, you have to run all of its parts independently. Each is released as a Docker image, on Docker Hub (see [hub.docker.com/u/proseim](https://hub.docker.com/u/proseim)) and on GitHub’s Container Registry (see [github.com/orgs/prose-im/packages](https://github.com/orgs/prose-im/packages)).
 
-! If you have any technical question while setting up your Prose Pod, feel free to [chat with our technical support team](#crisp-chat-open) which will gladly help you fix any issue you encounter.
+! If you have any technical question while setting up your Prose Pod, feel free to [chat with our technical support team](https://prose.org/contact/) which will gladly help you fix any issue you encounter.
 
 #### Example: Run with Docker Compose
 
@@ -208,7 +210,7 @@ If you see one that has exited, check its logs using:
 docker compose -f /etc/prose/compose.yaml logs --no-log-prefix -- {service_name}
 ```
 
-! If the error logs aren’t clear enough, don’t hesitate [reaching out to our technical support team](#crisp-chat-open).
+! If the error logs aren’t clear enough, don’t hesitate [reaching out to our technical support team](https://prose.org/contact/).
 
 ### Step 4: Configure the reverse proxy
 
@@ -272,7 +274,7 @@ curl http://localhost:3030/api/pod/version
 
 If you get a JSON payload back containing information about the versions of you Prose Pod’s components, it means everything should be working correctly. If you want to make sure everything is well configured or if the call fails, you will have to check the logs.
 
-! If logs don’t guide you to a solution, feel free to [chat with our technical support team](#crisp-chat-open) which will gladly help you fix any issue you encounter.
+! If logs don’t guide you to a solution, feel free to [chat with our technical support team](https://prose.org/contact/) which will gladly help you fix any issue you encounter.
 
 #### Checking logs using Docker Compose
 
@@ -288,13 +290,13 @@ If you don’t see the problem or are missing context, you should check *all* th
 docker compose -f /etc/prose/compose.yaml logs
 ```
 
-If the logs you see still don’t guide you to a solution, [reach out to our technical support team](#crisp-chat-open) which will gladly help you fix any issue you encounter.
+If the logs you see still don’t guide you to a solution, [reach out to our technical support team](https://prose.org/contact/) which will gladly help you fix any issue you encounter.
 
 ### Step 7: Initializing your Prose Pod
 
 Now that your Prose Pod is running, you need to create the first admin account, configure your DNS records and invite your first colleague. All of this can be done using the administration Dashboard which is accessible at `http://localhost:3030`.
 
-!! Those steps could also be done using the Prose Pod API directly but it’s pretty advanced and subject to changes so we won’t document it here. However, if you are interested in doing so you can [reach out to our technical support team](#crisp-chat-open) which will guide you into using the Pod API.
+!! Those steps could also be done using the Prose Pod API directly but it’s pretty advanced and subject to changes so we won’t document it here. However, if you are interested in doing so you can [reach out to our technical support team](https://prose.org/contact/) which will guide you into using the Pod API.
 
 However, you very likely don’t have access to a web browser on the machine where you are running the Prose Pod so you will have to create a first DNS record in order for you to access the Dashboard from your own web browser.
 
@@ -317,7 +319,7 @@ prose 10800 IN CNAME {hostname}
 
 Now, or after a few minutes (for your DNS provider to propagate the new records), you should be able to open `https://prose.{your_domain}:3030` in your web browser and see your Prose Pod Dashboard. If you get a SSL error, go back to [the “SSL certificates” section](#ssl-certificates) and make sure everything is correct.
 
-! If you can’t access your Dashboard at this point, feel free to [contact our technical support team](#crisp-chat-open) which will gladly help you fix your configuration.
+! If you can’t access your Dashboard at this point, feel free to [contact our technical support team](https://prose.org/contact/) which will gladly help you fix your configuration.
 
 Now that you have access to your Dashboard, you can follow [the “Initializing your workspace” section of the “Quickstart” guide](/guides/basics/quickstart/#initializing-your-workspace) to finish configuring your Prose Pod.
 
diff --git a/src/data/guides/operating/telemetry/index.md b/src/data/guides/operating/telemetry/index.md
@@ -21,4 +21,4 @@ For more information, see [“Configuration based on the environment variables
 You can also have a look at [prose-pod-api/local-run/otel-collector-config.yaml](https://github.com/prose-im/prose-pod-api/blob/4654bda8404a043f4d95a67d3cbd84667cd4f009/local-run/otel-collector-config.yaml)
 and [prose-pod-api/local-run/scenarios/default/local-run.env](https://github.com/prose-im/prose-pod-api/blob/4654bda8404a043f4d95a67d3cbd84667cd4f009/local-run/scenarios/default/local-run.env) for an example configuration we use when developing the Prose Pod API. The OpenTelemetry collector is defined in [prose-pod-api/local-run/compose.yaml](https://github.com/prose-im/prose-pod-api/blob/4654bda8404a043f4d95a67d3cbd84667cd4f009/local-run/compose.yaml#L81-L89) and receivers are started using [prose-pod-api/local-run/scripts/otlp](https://github.com/prose-im/prose-pod-api/blob/4654bda8404a043f4d95a67d3cbd84667cd4f009/local-run/scripts/otlp#L272). It’s not production ready but it’s a good base to understand how things relate to one another.
 
-! If you need help setting up telemetry for your self-hosted Prose Pod, feel free to [contact our technical support team](#crisp-chat-open) which will gladly help you set it up.
+! If you need help setting up telemetry for your self-hosted Prose Pod, feel free to [contact our technical support team](https://prose.org/contact/) which will gladly help you set it up.
diff --git a/src/data/guides/others/comparisons/index.md b/src/data/guides/others/comparisons/index.md
diff --git a/src/data/guides/others/index.md b/src/data/guides/others/index.md
diff --git a/src/data/guides/others/security/index.md b/src/data/guides/others/security/index.md
diff --git a/src/data/references/pod-api.md b/src/data/references/pod-api.md
@@ -5,4 +5,12 @@ UPDATED: 2025-05-15
 The Prose Pod API is one way to interact with a Prose Pod. It is what Dashboards use to configure a Prose Pod, and can be used as a way to automate things.
 
 It is subject to changes like new features and improvements, and since Prose Pods can be self-hosted a public documentation might not align with the version you deployed.
-To get the correct OpenAPI description for your Prose Pod, head over to `{prose_pod_dashboard_url}/api/api-docs/openapi.json`, or see it graphically at `{prose_pod_dashboard_url}/api/api-docs/redoc` (replacing `{prose_pod_dashboard_url}` by the URL of your Prose Pod Dashboard).
+
+# API Documentation
+
+**To get the correct OpenAPI description for your Prose Pod, either:**
+
+- Head over to: `{prose_pod_dashboard_url}/api/api-docs/openapi.json`
+- Or, see it graphically at: `{prose_pod_dashboard_url}/api/api-docs/redoc`.
+
+! Replace `{prose_pod_dashboard_url}` by the URL of your Prose Pod Dashboard.
diff --git a/src/data/references/pod-config.md b/src/data/references/pod-config.md
