1
0
mirror of https://github.com/spacebarchat/docs.git synced 2024-11-22 10:12:31 +01:00

📝 update documentation

This commit is contained in:
Flam3rboy 2021-05-15 13:08:36 +02:00
parent a90a039c14
commit 79f6c6f510
13 changed files with 267 additions and 156 deletions

View File

@ -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.
Note, however, that if the database already has a default value it won't update it.

View File

@ -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.
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.

View File

@ -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

View File

@ -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/``.
All Utility functions are in the directory `/src/util/`.

View File

@ -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

View File

@ -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`.
```
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:<password>@cluster.yjecb.mongodb.net/myFirstDatabase?retryWrites=true&w=majority`
Replace `<password>` 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
```

View File

@ -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.
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.

View File

@ -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

36
docs/ressources.md Normal file
View File

@ -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.

View File

@ -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>("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(<GuildDeleteEvent>{...});
```
### Example
Putting it all together:
```ts
await emitEvent({
event: "GUILD_DELETE",
@ -93,4 +104,4 @@ await emitEvent({
},
guild_id: guildID,
} as GuildDeleteEvent);
```
```

View File

@ -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<Permissions>;
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")) {
...
}
```
```

View File

@ -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)

View File

@ -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