From 79f6c6f5104eb913baebd4b01331f2eff62dd99f Mon Sep 17 00:00:00 2001 From: Flam3rboy <34555296+Flam3rboy@users.noreply.github.com> Date: Sat, 15 May 2021 13:08:36 +0200 Subject: [PATCH] :pencil: update documentation --- docs/API/configuration.md | 23 ++++--- docs/API/index.md | 11 +-- docs/API/installation.md | 34 ---------- docs/API/structure.md | 20 ++++-- docs/UI/installation.md | 28 ++++++-- docs/contributing.md | 117 +++++++++++++++++++++++++++----- docs/gateway/index.md | 11 +-- docs/gateway/installation.md | 30 -------- docs/ressources.md | 36 ++++++++++ docs/server_util/database.md | 35 ++++++---- docs/server_util/permissions.md | 17 +++-- docs/structure.md | 28 -------- mkdocs.yml | 33 ++++++++- 13 files changed, 267 insertions(+), 156 deletions(-) delete mode 100644 docs/API/installation.md delete mode 100644 docs/gateway/installation.md create mode 100644 docs/ressources.md delete mode 100644 docs/structure.md diff --git a/docs/API/configuration.md b/docs/API/configuration.md index 428cb64..ebddff0 100644 --- a/docs/API/configuration.md +++ b/docs/API/configuration.md @@ -1,4 +1,7 @@ +# Configuration + ## Philosophy + Every fosscord server instance should be completely configurable in every way, without the need to change the source code. The config should have reasonable defaults similar to discord. @@ -9,30 +12,34 @@ The config should be changeable over the admin fosscord-dashboard and update in The very first time the server starts, it saves to default config in the database. The next start it will load the config from the database. -## Getting Started -You **should not** ``get()`` the Config in the root of your file and it instead load the config every time you access a value +## Getting Started for Contributors + +You **should not** `get()` the Config in the root of your file and it instead load the config every time you access a value Import the file: + ```js // at the top of the file import the Config file from /src/util/Config.ts import Config from "/../util/Config"; ``` Access the Config in your route: + ```js router.get("/", (req: Request, res: Response) => { - // call Config.get() to get the whole config object and then just access the property you want - const { REGISTRATION_DISABLED } = Config.get().register + // call Config.get() to get the whole config object and then just access the property you want + const { REGISTRATION_DISABLED } = Config.get().register; }); ``` -``Config.get()`` returns the current config object and is not expensive at all +`Config.get()` returns the current config object and is not expensive at all ### Add own values to the Config -The default Config is located in ``/src/util/Config.ts`` and exports a ``interface DefaultOptions`` and a ``const DefaultOptions`` object with reasonable default values. -To add your own values to the config, add the properties to the ``interface`` with corresponding types and add default values to ``const DefaultOptions``. +The default Config is located in `/src/util/Config.ts` and exports a `interface DefaultOptions` and a `const DefaultOptions` object with reasonable default values. + +To add your own values to the config, add the properties to the `interface` with corresponding types and add default values to `const DefaultOptions`. Also you don't need to worry about updating "old config versions", because new values will automatically be synced with the database. -Note, however, that if the database already has a default value it won't update it. \ No newline at end of file +Note, however, that if the database already has a default value it won't update it. diff --git a/docs/API/index.md b/docs/API/index.md index 38bb479..730cf9b 100644 --- a/docs/API/index.md +++ b/docs/API/index.md @@ -1,8 +1,11 @@ -[Status overview](https://github.com/discord-open-source/discord-api/projects/2) +# API -This is a complete one-on-on clone of the discord api written in TypeScript. +### [Status overview](https://github.com/discord-open-source/discord-api/projects/2) + +This is the fosscord HTTP API Server. + +Every routes has its own [issue](https://github.com/fosscord/fosscord-api/issues?q=is%3Aopen+is%3Aissue+label%3ARoute). For documentation, head over to the [Discord docs](https://discord.dev). -## Installation -The API is not yet finished. \ No newline at end of file +If you want to work on a feature please comment on the corresponding issue so we can assign it you that nobody implements something twice. diff --git a/docs/API/installation.md b/docs/API/installation.md deleted file mode 100644 index 8660ab1..0000000 --- a/docs/API/installation.md +++ /dev/null @@ -1,34 +0,0 @@ -## Requirements -You should be familiar with: - -* [Git](https://git-scm.com/) -* [NodeJS](https://nodejs.org/) -* [TypeScript](https://www.typescriptlang.org/) -* [Mongoose](https://mongoosejs.com/) - -and the technologies we use for the API. - -## Getting Started -### Step 1 -Clone the repository: -```bash -git clone https://github.com/fosscord/fosscord-api -cd fosscord-api -``` -### Step 2 -Install dependencies: -```bash -npm install -``` -### Step 3 -Start: -``` -npm start -``` -### Step 4 -Navigate to `localhost:3001`. You will see the API in action. - -## Debugging -### VS Code -The Launch file configuration is in ``./vscode/launch.json``, -so you can just debug the server by pressing ``F5`` or the ``> Launch Server`` button diff --git a/docs/API/structure.md b/docs/API/structure.md index 0be22d3..c3ee99e 100644 --- a/docs/API/structure.md +++ b/docs/API/structure.md @@ -1,20 +1,26 @@ ## Translation -Additionally, we use [i18next](https://www.i18next.com/) to manage translation/localization in _some_ API Responses. -The ``.json`` language files are located in ``/locales`` and are separated by namespaces. +We use [i18next](https://www.i18next.com/) to manage translation/localization in _some_ API Responses. + +The `.json` language files are located in `/locales` and are separated by namespaces. ## Source code + We use [TypeScript](https://www.typescriptlang.org/) (JavaScript with types). -The ``.ts`` source files are located in ``/src/`` and will be compiled to ``.js`` in the ``/dist/`` directory. +The `.ts` source files are located in `/src/` and will be compiled to `.js` in the `/dist/` directory. ### Middlewares -All Express [Middlewares](http://expressjs.com/en/guide/writing-middleware.html) are in the directory ``/src/middlewares/`` and need to be manually loaded in ``/src/Server.ts``. + +All Express [Middlewares](http://expressjs.com/en/guide/writing-middleware.html) are in the directory `/src/middlewares/` and need to be manually loaded in `/src/Server.ts`. ### Routes -All Express [Router](http://expressjs.com/en/4x/api.html#router) Routes are in the directory ``/src/routes/`` and are automatically registered. + +All Express [Router](http://expressjs.com/en/4x/api.html#router) Routes are in the directory `/src/routes/` and are automatically registered. ### Models -All Database Typescript interface models are in the directory ``/src/models/`` + +All Database Typescript interface models are in the directory `/src/models/` ### Util -All Utility functions are in the directory ``/src/util/``. \ No newline at end of file + +All Utility functions are in the directory `/src/util/`. diff --git a/docs/UI/installation.md b/docs/UI/installation.md index a09e8d6..4ad0845 100644 --- a/docs/UI/installation.md +++ b/docs/UI/installation.md @@ -1,33 +1,47 @@ ## Requirements + You should be familiar with: -* [Git](https://git-scm.com/) -* [NodeJS](https://nodejs.org/) -* [SCSS](https://sass-lang.com/) _You could also just write plain CSS. (SCSS just adds some nice features)_ +- [Git](https://git-scm.com/) +- [NodeJS](https://nodejs.org/) +- [SCSS](https://sass-lang.com/) _You could also just write plain CSS. (SCSS just adds some nice features)_ and the technologies we use for the UI. ## Getting Started + ### Step 1 + Clone the repository: + ```bash -git clone https://github.com/fosscord/fosscord-api -cd fosscord-api +git clone https://github.com/fosscord/fosscord-ui +cd fosscord-ui ``` + ### Step 2 + Install dependencies: + ```bash npm install ``` + ### Step 3 + Compile the SCSS: + ``` npm run scss ``` + ### Step 4 + Open `./test/index.html` for see the test page. ## Debugging + ### VS Code -The Launch file configuration is in ``./vscode/launch.json``, -so you can just debug the server by pressing ``F5`` or the ``> Launch Server`` button + +The Launch file configuration is in `./vscode/launch.json`, +so you can just debug the server by pressing `F5` or the `> Launch Server` button diff --git a/docs/contributing.md b/docs/contributing.md index ff65da5..294ea45 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,19 +1,104 @@ -## Install the workspace -### Without automated scripts -#### Windows -1. Open up a Terminal. -2. Type this command: `curl https://raw.githubusercontent.com/fosscord/fosscord/main/scripts/setup/setup.bat --output setup.bat && setup.bat`. +# Contributing -#### Posix systems (MacOS, Linux...) -1. Open up a Terminal. -2. Type this command: `curl https://raw.githubusercontent.com/fosscord/fosscord/main/scripts/setup/setup.sh --output setup.sh && sh setup.sh`. +## Setup -### With automated scripts -This method need to have [Git](https://git-scm.com) installed. -#### Windows -1. Open up a Terminal. -2. Type this command: `git clone https://github.com/fosscord/fosscord && .\fosscord\scripts\setup\setup.bat`. +Clone all repositories: -#### Posix systems (MacOS, Linux...) -1. Open up a Terminal. -2. Type this command: `git clone https://github.com/fosscord/fosscord && sh ./fosscord/scripts/setup/setup.sh`. \ No newline at end of file +``` +git clone --recurse-submodules -j8 https://github.com/fosscord/fosscord +cd fosscord +``` + +### Mongodb + +#### MongoDB local server + +**Recommended**: Secure, control over data and lower latency + +[Install MongoDB](https://docs.mongodb.com/manual/installation/) locally and configure it: + +1. Edit the file `/etc/mongod.conf` and add this to the end: + +``` +replication: + replSetName: "rs0" +``` + +2. Restart MongoDB + +``` +systemctl reload mongod +``` + +3. Connect to mongodb + +``` +mongo +``` + +4. Setup replica set: + +``` +rs.initiate() +``` + +#### MongoDB Atlas/Cloud server + +**Easier setup**: But no data sovereignty and higher latency + +1. **Register/login** for free at [cloud.mongodb.com](https://cloud.mongodb.com/) (500mb limit) + +2. **Create a new cluster** + +3. **Configure cluster:** + + Sidebar -> Network Access (Security) -> IP Access List -> Add IP address -> + Either "Add current ip address" or "allow access from anywhere" or the ip of your server -> Confirm + +4. **Connect to cluster:** + + Sidebar -> Clusters -> Connect -> "Connect your application" -> **Copy connection string** + + Looks similar to this: `mongodb+srv://root:@cluster.yjecb.mongodb.net/myFirstDatabase?retryWrites=true&w=majority` + + Replace `` with your password and `myFirstDatabase` with a name of your choice + +5. **Add your connection string** to the `.env` files: + + Create `api/.env` and `gateway/.env` file and add this + + ``` + MONGO_URL=YourConnectionString + ``` + + replace `YourConnectionString` with the mongodb connection string + +--- + +### HTTP API Server + +``` +cd api +npm i +npm start +``` + +--- + +### WebSocket Gateway Server + +``` +cd gateway +npm i +npm start +``` + +--- + +### Docker + +Optionally if you want to use Docker: + +``` +docker-compose up +``` diff --git a/docs/gateway/index.md b/docs/gateway/index.md index ab4dbc3..03b871f 100644 --- a/docs/gateway/index.md +++ b/docs/gateway/index.md @@ -1,6 +1,9 @@ -[Status overview](https://github.com/fosscord/fosscord-gateway/projects/3) +# Gateway -This is a complete one-on-on clone of the discord gateway written in TypeScript. +### [Status overview](https://github.com/fosscord/fosscord-gateway/projects/3) -## Installation -The Gateway is not yet finished. \ No newline at end of file +This is the fosscord WebSocket Gateway Server. + +For documentation, head over to the [Discord docs](https://discord.dev). + +If you want to work on a feature please comment on the corresponding issue so we can assign it you that nobody implements something twice. diff --git a/docs/gateway/installation.md b/docs/gateway/installation.md deleted file mode 100644 index 1c62b1e..0000000 --- a/docs/gateway/installation.md +++ /dev/null @@ -1,30 +0,0 @@ -## Requirements -You should be familiar with: - -* [Git](https://git-scm.com/) -* [NodeJS](https://nodejs.org/) -* [TypeScript](https://www.typescriptlang.org/) - -and the technologies we use for the Gateway. - -## Getting Started -### Step 1 -Clone the repository: -```bash -git clone https://github.com/fosscord/fosscord-gateway -cd fosscord-gateway -``` -### Step 2 -Install dependencies: -```bash -npm install -``` -### Step 3 -Start: -``` -npm start -``` -## Debugging -### VS Code -The Launch file configuration is in ``./vscode/launch.json``, -so you can just debug the server by pressing ``F5`` or the ``> Launch Server`` button diff --git a/docs/ressources.md b/docs/ressources.md new file mode 100644 index 0000000..23e2a30 --- /dev/null +++ b/docs/ressources.md @@ -0,0 +1,36 @@ +## Project structure + +Fosscord consists of many repositories, which together make up the client and the server: + +### Server-side + +- [fosscord-api](https://github.com/fosscord/fosscord-api) is the REST HTTP API server. +- [fosscord-gateway](https://github.com/fosscord/fosscord-gateway) is the WebSocket Gateway server. +- [fosscord-media](https://github.com/fosscord/fosscord-media) will be the media server for voice and video sharing. +- [fosscord-dashboard](https://github.com/fosscord/fosscord-dashboard) An admin dashboard for the server (analytics, settings, administration, trust & safety) +- [fosscord-server-util](https://github.com/fosscord/fosscord-server-util) contains all shared logic like Database Models, Utility functions... +- [fosscord-cdn](https://github.com/fosscord/fosscord-cdn) is the content-delivery-content (CDN) that stores user uploaded images. +- [fosscord-docs](https://github.com/fosscord/fosscord-docs) Documentation of Fosscord + +### Client-side + +- [fosscord-ui](https://github.com/fosscord/fosscord-ui) is a user interface framework in the style of discord. +- [fosscord-themes](https://github.com/fosscord/fosscord-themes) contains all the official themes for the client. +- [fosscord-plugins](https://github.com/fosscord/fosscord-plugins) contains all the official plugins for the client. +- [fosscord-landingpage](https://github.com/fosscord/fosscord-landingpage) represents and explains the project. +- [fosscord-client](https://github.com/fosscord/fosscord-client) is the official Fosscord client. + +#### Discontinued + +- [react-native-withcss](https://github.com/fosscord/react-native-withcss) +- [css-mediaquery](https://github.com/fosscord/css-mediaquery) + +## Issues + +### Naming convention + +The issue name must have the main label as a prefix in brackets: e.g. `[Feature] Test` or `[Bug] Test`. + +The first letter of the prefix and the title must be uppercase. + +You are not allowed to use CAPS. diff --git a/docs/server_util/database.md b/docs/server_util/database.md index db09d29..16e5b8f 100644 --- a/docs/server_util/database.md +++ b/docs/server_util/database.md @@ -1,34 +1,39 @@ ## Philosophy + We create [mongoose](http://mongoosejs.com/) models and typescript interfaces for every data structure in the database. -We use BigInt's for ids instead of strings because of a better performance. _Note that they will get encoded if you send them_ +We use strings for all id's and for bitfields we use bigint's ## Documentation -Have a look at the mongoose documentation to get familiar with it: https://mongoosejs.com/docs/ -or watch this tutorial: https://youtu.be/WDrU305J1yw +Have a look at the [mongoose documentation](https://mongoosejs.com/docs/) to get familiar with it or watch this [tutorial](https://youtu.be/WDrU305J1yw) ## Getting Started + ```ts import mongoose from "mongoose"; ``` + and now you can query the database, here are some examples: + ```ts import { GuildModel} from "fosscord-server-util"; -await new GuildModel({ ... }).save(); +await new GuildModel({ ... }).save(); // inserts a new guild -const guild = await GuildModel.findOne({id: ...}).exec(); +const guild = await GuildModel.findOne({id: ... }).exec(); // searches for a guild ``` ## Models + We have mongoose Database Models and additionally [TypeScript Interfaces](https://www.typescriptlang.org/docs/handbook/interfaces.html). -They are located in the repo ``fosscord-server-util`` under ``/src/models/``. +They are located in the repo `fosscord-server-util` under `/src/models/`. To add your own Database Model, create a new file and export the model and the interface. Example: + ```ts export interface Event extends Document { guild_id?: bigint; @@ -51,19 +56,22 @@ export const EventSchema = new Schema({ export const EventModel = model("Event", EventSchema, "events"); ``` - ## Emit events + Most Routes modify the database and therefore need to inform the clients with events for data changes. _(Events are stored in a MongoDB Event Store collection and distributed to the individual gateway servers)_ -You can find all events on the [discord docs page](https://discord.com/developers/docs/topics/gateway#commands-and-events) +You can find all events on the [discord docs page](https://discord.com/developers/docs/topics/gateway#commands-and-events) and in [`server-util/src/modesl/Event.ts`](https://github.com/fosscord/fosscord-server-util/blob/master/src/models/Event.ts) + +To emit an event import the `emitEvent` function from `/src/util/Event.ts` -To emit an event import the ``emitEvent`` function from ``/src/util/Event.ts`` ```ts -import { emitEvent } from "./../../../util/Event"; +import { emitEvent } from "../../../util/Event"; ``` + this will take a the following parameters: + ```ts { guild_id?: bigint; // specify this if this event should be sent to all guild members @@ -74,7 +82,8 @@ this will take a the following parameters: } ``` -For easy intellisense, annotate the parameter with the corresponding Event interface from ``fosscord-server-util``: +For easy intellisense, annotate the parameter with the corresponding Event interface from `fosscord-server-util`: + ```ts import { GuildDeleteEvent } from "fosscord-server-util"; @@ -84,7 +93,9 @@ emitEvent({...}); ``` ### Example + Putting it all together: + ```ts await emitEvent({ event: "GUILD_DELETE", @@ -93,4 +104,4 @@ await emitEvent({ }, guild_id: guildID, } as GuildDeleteEvent); -``` \ No newline at end of file +``` diff --git a/docs/server_util/permissions.md b/docs/server_util/permissions.md index ccae576..254b8e8 100644 --- a/docs/server_util/permissions.md +++ b/docs/server_util/permissions.md @@ -1,12 +1,19 @@ -To get the permission for a guild member import the ``getPermission`` from ``fosscord-server-util``. +To get the permission for a guild member import the `getPermission` from `fosscord-server-util`. + ```ts -import { getPermission } from "fosscord-server-util" +import { getPermission } from "fosscord-server-util"; ``` -The first argument is the userid the second the guildid and the third channelid if you want to receive the permission for a certain channel. + +The first argument is the user_id the second the guild_id and the third channel_id + +If you want to receive the permission for a certain channel: + ```ts -getPermission(user_id: string, guild_id: string, channel_id?: string): Promise; +const permissions = await getPermission(user_id: string, guild_id: string, channel_id?: string) ``` + ### Example + ```ts const perms = await getPermission(req.userid, guild_id); perms.hasThrow("MANAGE_GUILD") // will throw an error if the users lacks the permission @@ -14,4 +21,4 @@ perms.hasThrow("MANAGE_GUILD") // will throw an error if the users lacks the per if (perms.has("MANAGE_GUILD")) { ... } -``` \ No newline at end of file +``` diff --git a/docs/structure.md b/docs/structure.md deleted file mode 100644 index 06f6863..0000000 --- a/docs/structure.md +++ /dev/null @@ -1,28 +0,0 @@ -## Issues -### Naming convention -The issue name must have the main label as a prefix in brackets: e.g. ``[Feature] Test`` or ``[Bug] Test``. - -The first letter of the prefix and the title must be uppercase. - -You are not allowed to use CAPS. - -## Project structure -Fosscord consists of many repositories, which together make up the client and the server: - -### Server-side -- [fosscord-server-util](https://github.com/fosscord/fosscord-server-util) contains all shared logic like Database Models, Utility functions... -- [fosscord-api](https://github.com/fosscord/fosscord-api) is the REST HTTP API server. -- [fosscord-gateway](https://github.com/fosscord/fosscord-gateway) is the WebSocket Gateway server. -- [fosscord-media](https://github.com/fosscord/fosscord-media) will be the media server for voice and video sharing. -- [fosscord-cdn](https://github.com/fosscord/fosscord-cdn) is the content-delivery-content (CDN) that stores user uploaded images. - -### Client-side -- [fosscord-ui](https://github.com/fosscord/fosscord-ui) is a user interface framework in the style of discord. -- [fosscord-themes](https://github.com/fosscord/fosscord-themes) contains all the official themes for the client. -- [fosscord-plugins](https://github.com/fosscord/fosscord-plugins) contains all the official plugins for the client. -- [fosscord-landingpage](https://github.com/fosscord/fosscord-landingpage) represents and explains the project. -- [fosscord-client](https://github.com/fosscord/fosscord-client) is the official Fosscord client. - -#### Discontinued -- [react-native-withcss](https://github.com/fosscord/react-native-withcss) -- [css-mediaquery](https://github.com/fosscord/css-mediaquery) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 67b698d..8897ef5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,10 @@ site_name: Fosscord Docs -repo_url: https://github.com/fosscord/fosscord-docs +repo_url: https://github.com/fosscord/fosscord +edit_uri: https://github.com/fosscord/fosscord-docs/edit/master/docs/ +site_description: Documentation of Fosscord a free open source selfhostable chat, voice and video discord-compatible platform plugins: - section-index + - search theme: name: material logo: assets/logo.png @@ -18,3 +21,31 @@ theme: name: Switch to light mode features: - navigation.expand + - navigation.instant + - navigation.tracking + - navigation.sections + - navigation.indexes + - navigation.top +nav: + - index.md + - ressources.md + - contributing.md + - "API": + - API/index.md + - API/structure.md + - API/configuration.md + - server_util/database.md + - server_util/permissions.md + - API/route.md + - "Gateway": + - gateway/index.md + - gateway/structure.md + - server_util/database.md + - server_util/permissions.md + - "UI Framework": + - UI/index.md + - UI/installation.md + - UI/write_a_component.md +markdown_extensions: + - pymdownx.highlight + - pymdownx.superfences