diff --git a/README.md b/README.md index c87ab4b..750b5b1 100644 --- a/README.md +++ b/README.md @@ -15,14 +15,14 @@ The UDN project aims to provide decentralized and localhost-able infrastructure # Contents -- [How it works](#how-it-works) - - [Channels](#channels) - - [Scalability](#scalability) - - [Example](#example) - [Administrator's Guide](#administrators-guide) - [Getting Started](#getting-started) - [Configuration](#configuration) - [Connecting Multiple Servers](#connecting-multiple-servers) +- [How it works](#how-it-works) + - [Channels](#channels) + - [Scalability](#scalability) + - [Example](#example) - [App Developer's Guide](#app-developers-guide) - [Guidelines](#guidelines) - [The Recommended Way](#the-recommended-way) @@ -30,6 +30,72 @@ The UDN project aims to provide decentralized and localhost-able infrastructure - [Changes](#changes) - [1.0.1](#1.0.1) +# Administrator's Guide + +## Getting Started + +The UDN project is based on [bun](https://bun.sh/), a faster and more streamlined alternative to node.js. + +1. Make sure bun is installed on your server. +2. Create a directory for your server and open it in a terminal. +3. Run `bun add @vdmdi/udn` to install the UDN server package. +4. Start the server with `bun run start`. +5. A configuration file will be created automatically. + +## Configuration + +By default, the configuration file looks like this: + +```JSON +{ + "port": 3000, + "privacy": "", + "imprint": "", + "connectedServers": [], + "subscribedChannels": [] +} +``` + +The port and channels are self-explanatory. For servers, you'll need to provide full addresses: + +```JSON +{ + "port": 3000, + "connectedServers": [ + "ws://192.168.0.100:3000", + "wss://192.168.0.200:3000" + ], + "subscribedChannels": [ + "secondary-channel-1", + "secondary-channel-2" + ] +} +``` + +Use `\n` to separate lines in the privacy policy. + +For the imprint field, enter a url. + +## Connecting Multiple Servers + +1. Add the WebSocket addresses of servers you want to connect to the `connectedServers` array in the configuration file. +2. Add secondary channels to the `subscribedChannels` array in the configuration file. + +Use the code example given above for reference. + +As explained in the _How it works_ section, you may want to use multiple servers on your network. In this case, consider the following: + +- Server-to-server-connections are bidirectional, so connecting server A to server B yields the same output as connecting server B to server A. +- Servers will attempt to restore lost connections to other servers periodically. +- You should make sure to evenly distribute your clients to different servers, so give your clients addresses of different servers to avoid everybody using the same one. +- Decide on one secondary channel for your network, configure all servers to subscribe, and make sure your users know this channel. +- If you are using self-signed certificates, your servers may refuse to connect to other TLS-enabled servers. +- In case your clients need to use `http`-served apps, these apps may refuse to connect to TLS-enabled servers. +- Therefore, you should have at least one TLS-enabled server, and at least one server without TLS. +- Configure the TLS-enabled servers to connect to those without TLS; connecting vice-versa may not work. + +--- + # How it works ## Introduction @@ -127,72 +193,6 @@ As you can see, there are many ways to connect multiple servers and communicate --- -# Administrator's Guide - -## Getting Started - -The UDN project is based on [bun](https://bun.sh/), a faster and more streamlined alternative to node.js. - -1. Make sure bun is installed on your server. -2. Create a directory for your server and open it in a terminal. -3. Run `bun add @vdmdi/udn` to install the UDN server package. -4. Start the server with `bun run start`. -5. A configuration file will be created automatically. - -## Configuration - -By default, the configuration file looks like this: - -```JSON -{ - "port": 3000, - "privacy": "", - "imprint": "", - "connectedServers": [], - "subscribedChannels": [] -} -``` - -The port and channels are self-explanatory. For servers, you'll need to provide full addresses: - -```JSON -{ - "port": 3000, - "connectedServers": [ - "ws://192.168.0.100:3000", - "wss://192.168.0.200:3000" - ], - "subscribedChannels": [ - "secondary-channel-1", - "secondary-channel-2" - ] -} -``` - -Use `\n` to separate lines in the privacy policy. - -For the imprint field, enter a url. - -## Connecting Multiple Servers - -1. Add the WebSocket addresses of servers you want to connect to the `connectedServers` array in the configuration file. -2. Add secondary channels to the `subscribedChannels` array in the configuration file. - -Use the code example given above for reference. - -As explained in the _How it works_ section, you may want to use multiple servers on your network. In this case, consider the following: - -- Server-to-server-connections are bidirectional, so connecting server A to server B yields the same output as connecting server B to server A. -- Servers will attempt to restore lost connections to other servers periodically. -- You should make sure to evenly distribute your clients to different servers, so give your clients addresses of different servers to avoid everybody using the same one. -- Decide on one secondary channel for your network, configure all servers to subscribe, and make sure your users know this channel. -- If you are using self-signed certificates, your servers may refuse to connect to other TLS-enabled servers. -- In case your clients need to use `http`-served apps, these apps may refuse to connect to TLS-enabled servers. -- Therefore, you should have at least one TLS-enabled server, and at least one server without TLS. -- Configure the TLS-enabled servers to connect to those without TLS; connecting vice-versa may not work. - ---- - # App Developer's Guide ## Guidelines @@ -242,7 +242,8 @@ export interface WebSocketMessage { 3. Stringify the object via `JSON.stringify()` 4. Send the string via WebSocket -# Changes +# Changes + ## 1.0.1: - Add privacy policy for public-facing instances - Add imprint link