Feature/add minimal react example (#26)

Co-authored-by: Michał Hoffmann <42720407+Crackhoff@users.noreply.github.com>
fishjam-dev · Sep 8, 2023 · f6f3b8f · f6f3b8f
1 parent de36efe
commit f6f3b8f
Show file tree

Hide file tree

Showing 17 changed files with 9,064 additions and 14 deletions.
diff --git a/.gitignore b/.gitignore
@@ -18,3 +18,6 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+# IntelliJ Idea
+.idea
diff --git a/docs/api_reference.md b/docs/api_reference.md
@@ -1,27 +1,29 @@
 # API Reference
 
 Jellyfish API is composed of three layers
+
 * a REST API for managing Jellyfish state
-* a WS connection for client SDK communication (socket path `/socket/peer`) 
+* a WS connection for client SDK communication (socket path `/socket/peer`)
 * a WS connection for server notifications (socket path `/socket/server`)
 
 You can find them here:
+
 * [OpenAPI REST description](api_reference/rest_api.md)
 * [Protobufs used by peer WS](https://github.com/jellyfish-dev/protos/blob/master/jellyfish/peer_notifications.proto)
 * [Protobufs used by server WS](https://github.com/jellyfish-dev/protos/blob/master/jellyfish/server_notifications.proto)
 
-The communication via WebSockets is done with use of [Protobuf](https://protobuf.dev) format.
-The very first message that has to be sent on either of WebSocket connections (**peer** to **Jellyfish** or 
+The communication via WebSockets uses [Protobuf](https://protobuf.dev) format.
+The very first message that has to be sent on either of the WebSocket connections (**peer** to **Jellyfish** or
 **your_backend_server** to **Jellyfish**) is `AuthRequest`.
 All supported messages are listed in [the Jellyfish protos repo](https://github.com/jellyfish-dev/protos).
 
-If you want to create your own Jellyfish SDK, the easiest way to reference to defined protobuf messages 
+If you want to create your own Jellyfish SDK, the easiest way to reference defined protobuf messages
 will be by adding *protos* to your git repository as a git submodule. You can do it with this command:
 
 ```bash
 git submodule add https://github.com/jellyfish-dev/protos
 ```
 
-You could also consider creating a script that will pull newest changes from the git submodule and compile 
-*.proto* files to your chosen programming language. 
+You could also consider creating a script that will pull the newest changes from the git submodule and compile
+*.proto* files to your chosen programming language.
 For reference, see [the script used in our Elixir SDK](https://github.com/jellyfish-dev/elixir_server_sdk/blob/master/compile_proto.sh).
diff --git a/docs/design_docs.md b/docs/design_docs.md
@@ -4,6 +4,6 @@ Crucial parts of Jellyfish architecture are always discussed and written down in
 of design documents.
 
 Each design document describes, in a nutshell, a few possible solutions or approaches to
-some problem and states which solution was accepted and why. 
+some problem and states which solution was accepted and why.
 
-The list of Jellyfish Design Docs is available [here](https://github.com/jellyfish-dev/jellyfish/tree/main/docs).
+The list of Jellyfish Design Docs is available [here](https://github.com/jellyfish-dev/jellyfish/tree/main/docs).
diff --git a/docs/examples.md b/docs/examples.md
@@ -1,4 +1,5 @@
 # Examples
 
 Jellyfish usage examples utilising server SDKs can be found in the following locations:
+
 - [Elixir](https://github.com/jellyfish-dev/jellyfish/tree/main/examples)
diff --git a/docs/getting_started/sdks.md b/docs/getting_started/sdks.md
@@ -8,8 +8,10 @@ See [here](./architecture.md) for more information about client and server SDKs.
 
 ## Client SDKs
 
-* [React](https://github.com/jellyfish-dev/react-client-sdk)
-* [TypeScript](https://github.com/jellyfish-dev/ts-client-sdk)
-* [IOS](https://github.com/jellyfish-dev/ios-client-sdk)
-* [Android](https://github.com/jellyfish-dev/android-client-sdk)
-* [React Native](https://github.com/jellyfish-dev/react-native-client-sdk)
+| SDK                                                                      | Resources                                                                                                                                                                                                                                                              |
+|--------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [React](https://github.com/jellyfish-dev/react-client-sdk)               | [React Minimal Working Example Guide](/docs/tutorials/minimal-working-example-react.mdx) <br/> [Jellyfish Videoroom](https://github.com/jellyfish-dev/jellyfish_videoroom) <br/> [Code examples](https://github.com/jellyfish-dev/react-client-sdk/tree/main/examples) |
+| [TypeScript](https://github.com/jellyfish-dev/ts-client-sdk)             | [Code examples](https://github.com/jellyfish-dev/ts-client-sdk/tree/main/examples)                                                                                                                                                                                     |
+| [IOS](https://github.com/jellyfish-dev/ios-client-sdk)                   | [Code example](https://github.com/jellyfish-dev/ios-client-sdk/tree/main/JellyfishClientDemo)                                                                                                                                                                          |
+| [Android](https://github.com/jellyfish-dev/android-client-sdk)           | [Code example](https://github.com/jellyfish-dev/android-client-sdk/tree/main/app)                                                                                                                                                                                      |
+| [React Native](https://github.com/jellyfish-dev/react-native-client-sdk) | [Code example](https://github.com/jellyfish-dev/react-native-client-sdk/tree/main/example)                                                                                                                                                                             |
diff --git a/docs/tutorials/ImageWrapper.tsx b/docs/tutorials/ImageWrapper.tsx
@@ -0,0 +1,26 @@
+// @ts-ignore
+import React from 'react';
+
+// @ts-ignore
+import useBaseUrl from '@docusaurus/useBaseUrl';
+// @ts-ignore
+import ThemedImage from '@theme/ThemedImage';
+
+type Props = {
+    url: string,
+    height?: number
+    alt: string,
+}
+
+export const ImageWrapper = ({ url, height, alt }: Props) => {
+    return <p style={{ display: "flex", justifyContent: "center" }}>
+        <ThemedImage
+            height={height}
+            alt={alt}
+            sources={{
+                light: useBaseUrl(url),
+                dark: useBaseUrl(url),
+            }}
+        />
+    </p>
+};
diff --git a/docs/tutorials/common/_jellyfish-architecture.mdx b/docs/tutorials/common/_jellyfish-architecture.mdx
@@ -0,0 +1,63 @@
+:::info
+
+You can learn more about Jellyfish architecture in [Jellyfish
+docs](/). This section provides a
+brief description aimed at front-end developers
+
+:::
+
+Let's introduce some concepts first:
+
+- **Peer** - A peer is a client-side entity that connects to the server to
+  publish, subscribe or publish and subscribe to tracks published by components
+  or other peers. You can think of it as a participant in a room. At the moment,
+  there is only one type of peer - WebRTC.
+- **Track** - An object that represents an audio or video stream. A track can be
+  associated with a local media source, such as a camera or microphone, or a
+  remote media source received from another user. Tracks are used to capture,
+  transmit, and receive audio and video data in WebRTC applications.
+- **Room** - In Jellyfish, a room serves as a holder for peers and components,
+  its function varying based on application. From a front-end perspective, this will
+  be probably one meeting or a broadcast.
+
+For a better understanding of these concepts here is an example of a room that
+holds a standard WebRTC conference from a perspective of the User:
+
+![Room example](/img/tutorials/room_example.png)
+
+In this example, peers stream multiple video and audio tracks. Peer #1 streams
+even two video tracks (camera and screencast track). You can differentiate
+between them by using track metadata. The user gets info about peers and their
+tracks from the server using Jellyfish Client. The user is also informed in real
+time about peers joining/leaving and tracks being added/removed.
+
+To keep this tutorial short we'll simplify things a little. Every peer will stream just one
+video track.
+
+### Connecting and joining the room
+
+The general flow of connecting to the server and joining the room in a standard
+WebRTC conference setup looks like this:
+
+![Connecting and joing the room](/img/tutorials/connection.png)
+
+The parts that you need to implement are marked in blue and things handled by
+Jellyfish are marked in red.
+
+Firstly, the user logs in. Then your backend authenticates the user and obtains
+a peer token. It allows the user to authenticate and join the room in Jellyfish
+Server. The backend passes the token to your front-end, and your front-end passes
+it to Jellyfish Client. The client establishes the connection with Jellyfish
+Server. Then Jellyfish Client sets up tracks (camera, microphone) to stream and
+joins the room on Jellyfish Server. Finally, your front-end can display the room
+for the user.
+
+For this tutorial we simplified this process a bit - you don't have to implement
+a backend or authentication. Jellyfish Dashboard will do this for you. It's also
+a nice tool to test and play around with Jellyfish. The flow with Jellyfish
+The dashboard looks like this:
+
+![Connecting and joing the room with dashboard](/img/tutorials/dashboard_connection.png)
+
+You can see that the only things you need to implement are interactions with the
+user and Jellyfish Client. This tutorial will show you how to do it.
diff --git a/docs/tutorials/common/_starting-dashboard.mdx b/docs/tutorials/common/_starting-dashboard.mdx
@@ -0,0 +1,31 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+There are a couple of ways to start the dashboard:
+
+<Tabs>
+  <TabItem value="main" label="Up-to-date version">
+
+The current version of the dashboard is ready to use and available
+[here](https://jellyfish-dev.github.io/jellyfish-dashboard/).
+Ensure that it is compatible with your Jellyfish server!
+Please note that this dashboard only supports secure connections (https/wss)
+or connections to localhost. Any insecure requests (http/ws) will be automatically blocked by the browser.
+
+  </TabItem>
+  <TabItem value="docker" label="Docker container">
+
+The dashboard is also published as a docker image, you can pull it using:
+
+```bash
+docker pull ghcr.io/jellyfish-dev/jellyfish-dashboard:0.1.0
+```
+
+  </TabItem>
+  <TabItem value="repo" label="Official repository">
+
+You can also clone our [repo](https://github.com/jellyfish-dev/jellyfish-dashboard)
+and run dashboard locally
+
+  </TabItem>
+</Tabs>
diff --git a/docs/tutorials/common/_starting-jellyfish-backend.mdx b/docs/tutorials/common/_starting-jellyfish-backend.mdx
@@ -0,0 +1,27 @@
+For testing, we'll run the backend locally using Docker image:
+
+```bash
+docker run -p 50000-50050:50000-50050/udp \
+           -p 4000:4000/tcp \
+           -e WEBRTC_USED=true \
+           -e INTEGRATED_TURN_PORT_RANGE=50000-50050 \
+           -e INTEGRATED_TURN_IP=<your ip address> \
+           -e INTEGRATED_TURN_LISTEN_IP=0.0.0.0 \
+           -e SERVER_API_TOKEN=development \
+           -e VIRTUAL_HOST=<your ip address> \
+           -e SECRET_KEY_BASE=secret \
+           -e PORT="4000" \
+           ghcr.io/jellyfish-dev/jellyfish:0.1.0-5e95d59
+```
+
+Make sure to set `INTEGRATED_TURN_IP` and `VIRTUAL_HOST` to your local IP address. Without it, the mobile device won't be able to connect to the backend.
+
+:::tip
+
+To check your local IP you can use this handy command (Linux/macOS):
+
+```bash
+ifconfig | grep "inet " | grep -Fv 127.0.0.1 | awk '{print $2}'
+```
+
+:::