✨📝(website): further enrich & overhaul docs

docs/astro.config.mjs

@@ -14,6 +14,13 @@ export default defineConfig({
       customCss: [
         './src/styles/custom.css',
       ],
+      head: [{
+        tag: 'meta',
+        attrs: {
+          property: 'og:image',
+          content: 'https://xplex.me/preview.png',
+        },
+      }],
       social: {
         github: 'https://github.com/debloper/xplex',
       },
@@ -29,6 +36,8 @@ export default defineConfig({
           label: 'Installation',
           items: [
             'setup/index',
+            'setup/host',
+            'setup/precheck',
             'setup/docker',
             'setup/native',
           ],

docs/src/components/Xplex.astro

@@ -1,11 +1,13 @@
 ---
 const {
   content = 'xplex',
-  color = '#b0b',
   isHQ = false
 } = Astro.props;
 
-const HQ = isHQ ? "HQ" : "";
+const HQ = isHQ ? "<sup>HQ</sup>" : "";
 ---
+<b set:html={content+HQ}></b>
 
-<b style=`color: ${color};`>{ content || 'xplex' }<sup>{ HQ }</sup></b>
+<style>
+  b { color: var(--sl-color-accent); }
+</style>

docs/src/content/docs/index.mdx

@@ -1,12 +1,15 @@
 ---
-title: Welcome
-description: Multi-stream your content with xplex, to as many streaming platforms as you want!
+title: Multi-stream Renaissance
+description: xplex—your personal, self-hosted, open source, multi-streaming server
+head: # https://github.com/withastro/starlight/discussions/1103#discussioncomment-7628411
+  - tag: style
+    content: ":root { --sl-content-width: 75rem !important; }"
 template: splash
 # banner:
 #   content: We just launched something cool! <a href="https://example.com">Check it out</a>
 hero:
   title: The renaissance will not be televised
-  tagline: But it <b>will</b> be streamed LIVE&mdash;with <b style="color:#b0b;">xplex</b>
+  tagline: But it <b>will</b> be multi-streamed LIVE&mdash;with <b style="color:#b0b;">xplex</b>
   image:
     file: ../../../public/favicon.svg
     alt: xplex logo

docs/src/content/docs/intro/index.mdx

@@ -12,7 +12,7 @@ import Xplex from '@components/Xplex.astro';
 
 ## What does it do?
 
-<Xplex /> acts as a bridge between your streaming software (e.g. OBS Studio, Streamlabs OBS, XSplit etc.) and the streaming services (e.g. Twitch, YouTube etc.). It takes the stream from your streaming software and goes live on all of the streaming services you've asked it to &mdash; all at once!
+<Xplex /> acts as a bridge between your streaming software (e.g. OBS Studio, Streamlabs OBS, XSplit etc.) and the streaming services (e.g. Twitch, YouTube etc.). It takes the stream from your streaming software and goes live on all of the streaming services you've asked it to &mdash; **all at once**!
 
 :::note[Think of it this way...]
 Imagine <Xplex /> is an HDMI splitter. You connect your streaming software to <Xplex /> (like you connect your HDMI source to the splitter), and <Xplex /> forwards the stream to multiple streaming services (like the splitter forwards the video to multiple screens).
@@ -42,13 +42,23 @@ There's no transcoding involved, so not only the stream quality remains the same
 
 :::note[Choosing Cloud Host]
 Here's a price comparison of cheapest compute units provided by some popular cloud providers:
-| Cloud Host   | Compute      | Bandwidth | Cost       |
-|--------------|--------------|-----------|------------|
-| DigitalOcean | 1core, 0.5GB | 500GB     | $4/month   |
-| Linode       | 1core, 1.0GB | 1000GB    | $5/month   |
-| Vultr        | 1core, 0.5GB | 500GB     | $2.5/month |
+| Cloud Host   | Compute      | Bandwidth | Cost/month | Referral Link |
+|--------------|--------------|-----------|------------|---------------|
+| DigitalOcean | 1core, 0.5GB | 500GB     | $4         | [$200 starting credit](https://m.do.co/c/97a76c3ca7ad)         |
+| Linode       | 1core, 1.0GB | 1000GB    | $5         | Coming Soon                                                    |
+| Vultr        | 1core, 0.5GB | 500GB     | $2.5       | [$10 starting credit](https://www.vultr.com/?ref=9638716)      |
+
+Either of them should be a good option; however, the author has only extensively used & tested DigitalOcean. If you face any quirk or edge case on the other servers, please [let us know](https://github.com/debloper/xplex/issues/new).
+:::
+
+:::tip[Free Test Run]
+By using the referral links to sign up, you'll receive ample credits to explore `xplex` for a couple of months at no cost to you.
+
+While we have no affiliation with the mentioned cloud providers, should you choose to continue their services after the credits expire and spend a small amount ($25 on DO, $10 on Vultr), we'll receive an one-time cloud credit of the same value.
+
+There's no obligation, but your support would make a meaningful contribution to the project.
 :::
 
 ---
 
-With all that said, hopefully you now have a good idea of what to expect from <Xplex /> as a user. But, if you're still curious to know more about its internal details, let's dive in a bit deeper...
+Hopefully you now have a good idea of what to expect from <Xplex /> as a user. But, if you're still curious to know more about its internal details, let's dive in a bit deeper...

docs/src/content/docs/intro/internals.mdx

@@ -3,21 +3,83 @@ title: Technical Overview
 description: The explanation of xplex's technical implementation.
 ---
 import Xplex from '@components/Xplex.astro';
+import { FileTree } from '@astrojs/starlight/components';
 
-## How does it work?
+## Strategic Abstract
 
-At its core, <Xplex /> is an [rtmp-enabled](https://github.com/arut/nginx-rtmp-module) [nginx server](http://nginx.org/) that splits & pushes incoming RTMP streams to one or more pre-configured RTMP endpoints.
+At its core, <Xplex /> is an [rtmp-enabled](https://github.com/arut/nginx-rtmp-module) [nginx server](http://nginx.org/) that pushes identical copies of incoming RTMP streams to one or more pre-configured RTMP endpoints.
 
-It also provides a simple web-based dashboard with REST API &mdash; called <Xplex isHQ="true" /> &mdash; to conveniently manage the ingest URLs.
+It also provides a simple web-based dashboard with REST API &mdash; called <Xplex isHQ /> &mdash; to conveniently manage the ingest URLs.
+
+## Design Principles
+
+<details>
+<summary>Effective</summary>
+make it do what it's supposed to do
+</details>
+<details>
+<summary>Efficient</summary>
+do it with minimal teleological overhead
+</details>
+<details>
+<summary>Elegant</summary>
+and with fluent grace of pieces falling in place
+</details>
+<details>
+<summary>Extensible</summary>
+while leaving room for progressive enhancements
+</details>
+
+## Repository Overview
+
+<FileTree>
+
+- .github/ ---> actions & workflows automations
+- app/ -------> source files for <Xplex isHQ /> server
+- conf/ ------> nginx configs for HTTP & RTMP
+- docs/ ------> website with landing page & docs
+- .gitignore
+- Dockerfile -> containerization instructions
+- **LICENSE** ---> source is available under **MPLv2.0**
+- README.md
+- setup.sh ---> <Xplex /> manual setup script
+- xplex.sh ---> <Xplex /> container startup script
+
+</FileTree>
+
+## Operational Steps
+
+- **There's no official `nginx-rtmp` container; so first, we built one from scratch.**
+  - You can build it by explicitly mentioning the target as `nginx` instead of `xplex` as the default target; e.g. `docker build --target nginx -t xplex/nginx .`
+- **Next up we implant the `nginx-rtmp` installation on a Node.js base image.**
+  - This is simpler than installing Node.js on the `nginx-rtmp` image.
+  - We may want to move out or refactor Node.js dependency in future.
+- **Then we apply configurations for the HTTP & RTMP servers.**
+  - But we don't start the nginx process yet
+  - Better to start the Node.js server (on port 8080) first
+  - Else nginx won't reverse proxy it to port 80 without another reload
+  - Reverse proxying is not functionally necessary for the setup to work, but it's the easiest way to infer that the setup is working by being able to access the dashboard over port 80.
+- **Then we install <Xplex isHQ /> as a simple Node.js app to manage the ingest URLs**
+- **Finally, we start the processes inside the container in sequence**
+  - The Node.js server is started first & sent to background
+  - Then the nginx process is started with daemon mode off
+  - This is needed to keep the container running & also helpful for following logs
 
 ## Future Roadmap
 
-- [ ] SRT support
-- [ ] RTMPS support
 - [ ] <Xplex isHQ /> improvements
 - [ ] Let's Encrypt integration
+- [ ] Unit & integration tests
+- [ ] x86, ARM, RISC-V support
+
+## Stretch Goals
+- [ ] RTMPS support
+- [ ] RTSP support
+- [ ] SRT support
+- [ ] HLS support
+- [ ] NDI support
 - [ ] ...and more
 
-:::danger[Stub Alert]
-This article needs more love. Please check back later.
+:::note[Missing Something?]
+If you can think of the missing pieces that will make understanding this technical overview easier and more enjoyable; or you have a question about the implementation, please [let us know](https://github.com/debloper/xplex/issues/new).
 :::

docs/src/content/docs/setup/docker.mdx

@@ -3,42 +3,95 @@ title: Run as a Docker Container
 description: A comprehensive guide on how to setup xplex with Docker containers.
 ---
 import Xplex from '@components/Xplex.astro';
-import { LinkCard, Steps } from '@astrojs/starlight/components';
+import { Badge, Card, Steps } from '@astrojs/starlight/components';
 
-:::note[Prerequisites' Checklist]
-To run <Xplex /> as a Docker container, you'll need to ensure that:
-- [ ] You have root access on the system.
-- [ ] You have [Docker installed](https://docs.docker.com/get-docker/) on your system.
-- [ ] There's no existing **nginx** service running on the system.
-- [ ] Port `80` (HTTP) and `1935` (RTMP) are available & not blocked by firewall.
+:::note[DON'T PANIC]
+You may be running Docker for the first time today, but that doesn't mean it can't be fun!
+:::
 
-Once you've verified all of the above, you're good to go!
+:::tip[Express Queue]
+If you went with the <Badge text="1-click setup option" variant="caution" /> with [Docker preinstalled system image](/setup/host#option-1-set-up-a-new-cloud-host)&mdash;then just skip the next queue of installing Docker and jump ahead to the [interesting bit](/setup/docker#run-the-docker-container) below.
 :::
 
-<Steps>
+## Install Docker
+
+Installing Docker can be quite an involved process; especially considering all the platform and architecture variants it has to cover. It's best to follow the [official installation guide](https://docs.docker.com/engine/install/) as it's canonical & comprehensive&mdash;covering all the supported platforms.
+
+But for the most likely scenario of **installing Docker on a Debian based system**... in short:
 
-1. **Run the <Xplex /> container**
+<Steps>
 
+1. <details>
+   <summary>Update the package index & install certs</summary>
    ```bash
-   docker run -d --name xplex -p 80:80 -p 1935:1935 xplex/xplex
+   sudo apt update
+   sudo apt install ca-certificates curl
+   ```
+   </details>
+2. <details>
+   <summary>Add Docker's official GPG key</summary>
+   ```bash
+   sudo install -m 0755 -d /etc/apt/keyrings
+   sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
+   sudo chmod a+r /etc/apt/keyrings/docker.asc
+   ```
+   </details>
+3. <details>
+   <summary>Add Docker repository to sources list</summary>
+   ```bash
+   echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+   sudo apt update
+   ```
+   </details>
+4. <details>
+   <summary>Install Docker & its supporting package</summary>
+   ```bash
+   sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+   ```
+   </details>
+5. <details>
+   <summary>Start Docker service & enable on boot</summary>
+   ```bash
+   sudo systemctl start docker
+   sudo systemctl enable docker
+   ```
+   </details>
+6. <details>
+   <summary>Verify installation by running container</summary>
+   ```bash
+   docker --version
+   sudo docker run hello-world
    ```
+   </details>
+
+</Steps>
+
+If you're new to all this and this seems a bit overwhelming; that's understandable.
 
-2. **Mark it DONE on your TODO list**
+Which is why, <Badge text="we recommend" variant="caution" /> going with a [system image with Docker preinstalled](/setup/host#option-1-set-up-a-new-cloud-host).
 
-   No, really... That's it! You're done.
 
-   You can now access your <Xplex isHQ="true" /> dashboard at `http://<hostname-or-IP>/`
+## Check Firewall Rules
+
+If the host is running a firewall, make sure to allow traffic on ports `80` (HTTP) & `1935` (RTMP). Follow [the firewall section](/setup/native#manage-firewall-rules) from manual installation guide to manage firewall if you need.
+
+
+## Run the Docker Container
+
+<Steps>
+
+1. ```bash title="Run the xplex container"
+   docker run -d --name xplex -p 80:80 -p 1935:1935 xplex/xplex
+   ```
+
+2. Open a browser & access your <Xplex isHQ /> dashboard at `http://<hostname-or-IP>/`
 
 </Steps>
 
----
+<span style="font-size: 4rem;">🎉🎉🎉</span>
 
-:::caution[Check Firewall Rules]
-If the host system is running a firewall, make sure to allow traffic on ports `80` (HTTP) & `1935` (RTMP). Follow [the firewall section](/setup/native#manage-firewall-rules) from manual installation guide to manage firewall.
-:::
+That's it... you now have a running <Xplex /> instance, ready for you to set up ingest URLs.
 
-<LinkCard
-  title="Jump to the usage section"
-  description="Learn how to use <b>xplex</b><sup>HQ</sup> to configure <b>xplex</b> with multi-streaming ingest endpoints."
-  href="/usage"
-/>
+<Card title="<a href='/usage'>Jump to the usage section</a>" icon="random">
+  Learn how to use <Xplex isHQ /> to configure <Xplex /> with multi-streaming ingest endpoints.
+</Card>