Spacebar/docs
1
0
Fork 0
mirror of https://github.com/spacebarchat/docs.git synced 2024-11-26 04:02:32 +01:00
Code Issues Releases Activity

Rewrite for maddy/refactor branch

Browse Source
This commit is contained in:
Madeline 2022-12-20 23:29:35 +11:00
parent 78aa838d8e
commit 1e43aeaed6
No known key found for this signature in database
GPG Key ID: 1958E017C36F2E47
46 changed files with 493 additions and 1258 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/api/encryption.md
View File

@ -1,17 +0,0 @@
# Encryption
Note: End-to-end encryption is currently in the planning stage. Once MLS stabilises, we will start the implementation
## Philosophy for the planned implementation
Everything should be end-to-end encrypted by default.
Everything should be configurable by the user/admin to their security needs.
Once encryption is enabled you will not be able to disable it anymore. _(Plain text channels need be created as such)_
End to end encryption should also be possible on unsupported servers e.g. discord.com. _(through special formatted messages)_
Based on the concept that the server cannot be trusted and could be compromised.
_more coming soon_

5
docs/api/index.md
View File

@ -1,5 +0,0 @@
# API
## [Routes](routes/)
## [User rights](rights/)

79
docs/api/rights.md
View File

@ -1,79 +0,0 @@
# User rights
## Introduction
User rights are instance-wide per-user permission toggle that affects instance-wide permissions of users,
such as the ability to edit one's own messages.
You may modify a users rights by editing the `rights` column in the `users` table.
See [Database](/server/database) and [Configuration](/server/configuration) for more information.
The rights value is a bitfield string, and to grant multiple rights you must add their values together.
For example, to grant `CREATE_GUILDS` and `SEND_MESSAGES`, grant the user(s)
`(1 << 15) = 32768` +
`(1 << 25) = 33554432` =
`33587200`
!!! warning "The default rights are current `0`. ***NEVER*** set default rights to `1` ( `OPERATOR` ), as this allows ANY USER to perform ANY ACTION including shutting down the server. ONLY EVER GIVE YOURSELF `OPERATOR` RIGHTS."
The rights value `646392577024` emulates the rights of users on Discord.com, granting:
| Default Rights | | |
|---------------------|-------------------------|---------------------------|
| `CREATE_CHANNELS` | `SELF_DELETE_MESSAGES` | `USE_ACHIEVEMENTS` |
| `CREATE_DMS` | `SELF_EDIT_MESSAGES` | `SELF_ADD_DISCOVERABLE` |
| `CREATE_DM_GROUPS` | `SELF_EDIT_NAME` | `SELF_LEAVE_GROUPS` |
| `CREATE_GUILDS` | `SEND_MESSAGES` | `KICK_BAN_MEMBERS` |
| `CREATE_INVITES` | `USE_ACTIVITIES` | `SELF_ADD_REACTIONS` |
| `CREATE_ROLES` | `USE_VIDEO` | `PIN_MESSAGES` |
| `CREATE_TEMPLATES` | `USE_VOICE` | `SELF_DELETE_DISABLE` |
| `CREATE_WEBHOOKS` | `INVITE_USERS` | `CREATE_APPLICATIONS` |
| `JOIN_GUILDS` | | |
Below is a list of all available rights
| Right | Value | Grants when it's 1 |
| --------------------------| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPERATOR` | 1 << 0 | All rights |
| `MANAGE_APPLICATIONS` | 1 << 1 | Ability to alter or remove others' applications |
| `MANAGE_GUILDS` | 1 << 2 | Same as the per-guild `MANAGE_GUILD` permission, but applies to all guilds and DM channels, can join any guild without invite |
| `MANAGE_MESSAGES` | 1 << 3 | Can delete or edit any message they can read |
| `MANAGE_RATE_LIMITS` | 1 << 4 | Add, change, define rate limits of other users, can also grant others `BYPASS_RATE_LIMITS` when combined with `BYPASS_RATE_LIMITS` and `MANAGE_USERS` |
| `MANAGE_ROUTING` | 1 << 5 | Create, alter, enable, disable custom message routing rules in any channel/guild |
| `MANAGE_TICKETS` | 1 << 6 | Respond to or resolve other users' support tickets |
| `MANAGE_USERS` | 1 << 7 | Create, alter, remove, ban users; create, modify, remove user groups |
| `ADD_MEMBERS` | 1 << 8 | Can manually add members into their guilds and group DMs |
| `BYPASS_RATE_LIMITS` | 1 << 9 | Makes the user exempt from all rate limits |
| `CREATE_APPLICATIONS` | 1 << 10 | Can create, edit, remove own applications |
| `CREATE_CHANNELS` | 1 << 11 | Can create guild channels and custom channels |
| `CREATE_DMS` | 1 << 12 | Can create 1:1 DMs (a user without `SEND_MESSAGES` cannot be added however) |
| `CREATE_DM_GROUPS` | 1 << 13 | Can create group DMs (a user without `SEND_MESSAGES` cannot be added however) |
| `CREATE_GUILDS` | 1 << 14 | Can create guilds |
| `CREATE_INVITES` | 1 << 15 | Can create mass invites in the guilds that they have `CREATE_INSTANT_INVITE` |
| `CREATE_ROLES` | 1 << 16 | Can create roles and per-guild or per-channel permission overrides in the guilds that they have permissions |
| `CREATE_TEMPLATES` | 1 << 17 | Can create templates for guilds, custom channels and channels with custom routing |
| `CREATE_WEBHOOKS` | 1 << 18 | Can create webhooks in the guilds that they have permissions |
| `JOIN_GUILDS` | 1 << 19 | Can join guilds by using invites or vanity names |
| `PIN_MESSAGES` | 1 << 20 | Can modify the pinned messages in the guilds that they have permission |
| `SELF_ADD_REACTIONS` | 1 << 21 | Can react to messages, subject to permissions |
| `SELF_DELETE_MESSAGES` | 1 << 22 | Can delete own messages |
| `SELF_EDIT_MESSAGES` | 1 << 23 | Can edit own messages |
| `SELF_EDIT_NAME` | 1 << 24 | Can edit own username, nickname and avatar |
| `SEND_MESSAGES` | 1 << 25 | Can send messages in the channels that they have permissions |
| `USE_ACTIVITIES` | 1 << 26 | Can use voice activities, such as watch together or whiteboard |
| `USE_VIDEO` | 1 << 27 | Can use video and screenshare in guilds/channels that they have permissions |
| `USE_VOICE` | 1 << 28 | Can use voice in guilds/channels that they have permissions |
| `INVITE_USERS` | 1 << 29 | Can create user-specific invites in the guilds that they have `INVITE_USERS` |
| `SELF_DELETE_DISABLE` | 1 << 30 | Can delete/disable own account |
| `DEBTABLE` | 1 << 31 | Can use pay-to-use features once paid |
| `CREDITABLE` | 1 << 32 | Can earn money using monetization features in the guilds that have `MONETIZATION_ENABLED` |
| `KICK_BAN_MEMBERS` | 1 << 33 | Can kick or ban guild or group DM members in the guilds/groups that they have KICK_MEMBERS, or BAN_MEMBERS |
| `SELF_LEAVE_GROUPS` | 1 << 34 | Can leave the guilds or group DMs that they joined on their own (one can always leave a guild or group DMs they have been force-added) |
| `PRESENCE` | 1 << 35 | Inverts the presence confidentiality default (OPERATOR's presence is not routed by default, others' are) for a given user |
| `SELF_ADD_DISCOVERABLE` | 1 << 36 | Can mark discoverable guilds that they have permissions to mark as discoverable |
| `MANAGE_GUILD_DIRECTORY` | 1 << 37| Can change anything in the primary guild directory |
| `POGGERS` | 1 << 38 | Can send confetti, screenshake, random user mention (@someone) |
| `USE_ACHIEVEMENTS` | 1 << 39 | Can use achievements and cheers |
| `INITIATE_INTERACTIONS` | 1 << 40 | Can initiate interactions |
| `RESPOND_TO_INTERACTIONS` |1 << 41| Can respond to interactions |
| `SEND_BACKDATED_EVENTS` | 1 << 42 | Can send backdated events |

BIN
docs/assets/architecture.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 677 KiB

BIN
docs/assets/banner.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 190 KiB

3
docs/bots/index.md
View File

@ -1,3 +0,0 @@
# Bots
## [Setup](setup)

79
docs/bots/setup.md
View File

@ -1,79 +0,0 @@
# Setup
Fosscord is backwards compatible to discord, which means you can reuse your existing discord bot library and only need to change the api endpoints.
Currently the developer portal is not fully implemented yet, and Fosscord's bot dashboard is still in development. Until then you can use regular user accounts. Similarly in the instances where the human/bot distinction is disabled, just a regular user would be used. (aka user botting)
## Retrieve the user token:
1. Open the instance in your browser
2. Logout of your current account
3. Register a new account
4. Enable DevTools (hit `F12` or `Right click on the page -> Inspect`).
5. Open the network tab inside of DevTools
6. Enable the xhr/fetch request filter
7. Execute any kind of action (navigate to a channel, send a message)
8. Click on any (api) request
9. Inside of "Request Headers" copy the value of the `authorization` header.
![Retrieve user token](https://user-images.githubusercontent.com/34555296/136654084-73c2c2a2-0a54-46f3-b10d-ff20cd64c656.jpg)
**Done**: You now can use this copied token to login with your bot libary or authorize any api request by putting it inside the authorization header.
**Notice**: Currently you can but don't need to prefix the token with "`Bot`".
## Libraries
Change `https://api.fosscord.com` to your desired endpoint.
Replace `your token here` with your copied token.
### Discord.js
Inside the client option you can specify the api endpoint:
```js
const { Client } = require('discord.js')
const client = new Client({
http: {
version: 9,
api: 'https://api.fosscord.com',
cdn: 'https://cdn.fosscord.com',
invite: 'https://fosscord.com/invite'
}
})
client.login('your token here')
```
### Discord.py
```py
import discord
discord.http.Route.BASE = "https://api.fosscord.com"
client = discord.Client()
client.run('your token here')
```
### JDA
```java
import java.lang.reflect.*;
import net.dv8tion.jda.internal.requests.*;
public static void main(String[] args) {
JDA jda = JDABuilder.createDefault("your token here").build();
Field field = Requester.class.getDeclaredField("DISCORD_API_PREFIX")
field.setAccessible(true);
Field modifiers = Field.class.getDeclaredField("modifiers");
modifiers.setAccessible(true);
modifiers.setString(field, field.getModifiers() & ~Modifier.FINAL);
field.set(null, "https://api.fosscord.com");
}
```

53
docs/client/connect.md
View File

@ -1,53 +0,0 @@
# Client
## Use your Discord client for your instance
In order to set your **ENDPOINT** follow these simple steps
- Go to `%appdata%/yourdiscord_client` (Example: `%appdata%/discordptb`)
- There is a file called `settings.json`. It should look like: (`Contents can be different depending on your Discord's client settings`)
```js
{
"IS_MAXIMIZED": true,
"IS_MINIMIZED": false,
"WINDOW_BOUNDS": {
"x": 335,
"y": 86,
"width": 940,
"height": 600
},
"BACKGROUND_COLOR": "#202225"
}
```
- Add this line to `settings.json`
```js
"WEBAPP_ENDPOINT" : "https://your_fosscord_instance_url"
```
- It should look like this after you add the line:
```js
{
"IS_MAXIMIZED": true,
"IS_MINIMIZED": false,
"WINDOW_BOUNDS": {
"x": 335,
"y": 86,
"width": 940,
"height": 600
},
"BACKGROUND_COLOR": "#202225",
"WEBAPP_ENDPOINT" : "https://your_fosscord_instance_url"
}
```
- Note: If you are the instance owner make sure to install `@yukikaze-bot/erlpack` using `npm i @yukikaze-bot/erlpack` in order for Electron clients being able to connect to your instance by changing the endpoint
- After this quit your Discord client, reopen it and you are all done!
// Made by ImAaronFR
// Added to PR and specific folder by AToska21
// Edited by Z3naero

5
docs/client/index.md
View File

@ -1,5 +0,0 @@
# Client
## [Plugins](plugins/)
## [Themes](themes/)

29
docs/client/plugins.md
View File

@ -1,29 +0,0 @@
# Plugins
## Philosophy
- Plugins are executed in their environment to prevent security issues.
- Plugins can create their own UI and loaded in a separate view _(similar to vscode extensions)_.
- Plugins can access the component Api and therefore extend the client UI.
- Plugins can access the WebSocket Connection/Rest API and intercept/transform events.
- Plugins are restricted and can only do actions with the corresponding permission.
- Plugins should be accessible through a store that needs to verify the plugins (with dev options to load plugins/add other stores).
## Permissions
- Can't access the user's token (token plugins should rather be directly integrated into the client (e.g. account switcher)).
- All permissions must meet the purpose of the plugin and must justify why they need the certain permission to be approved.
- Shouldn't be able to make any request, except if it:
- Requests permission to access the api of the network.
- Requests permission to access a specific domain (e.g. plugins backend).
- Requests permission to access all domains.
- Shouldn't be able to intercept events, except if it:
- Requests permission to a specific event(s).
- Requests permission to all events.
- Needs to request permission to be able to extend the client's UI.
**_more coming soon_**

11
docs/client/themes.md
View File

@ -1,11 +0,0 @@
# Themes
## Philosophy
- Themes should look the same on all platforms.
- Themes should be made with an visual theme editor to easily create and edit your own themes.
- Themes should be combinable to use multiple themes at once.
- Themes should be installed and submitted through a theme store with voting options.
- Guilds should be able to specify their own themes for compatible clients.
**_more coming soon_**

48
docs/contributing/conduct.md Normal file
View File

@ -0,0 +1,48 @@
# Code of Conduct
By contributing to or interacting with Fosscord or Fosscord community spaces, you accept the code of conduct.
This code of conduct is based on the Artemis Lena Code of Conduct by FantasyCookie17. As it is licensed under CC0, it may be used by other communities in modified or unmodified form without permission from the author. Its purpose is to ensure a civilised, tolerant, compassionate, help, pluralistic, and peaceful style of communication.
Fosscord community spaces includes Fosscord github repositories and Fosscord development guilds (be it on Discord.com or Fosscord instances mananged by the Fosscord maintainers group).
By contributing to any Fosscord projects (for example, through pull request) you guarantee that you have the rights to resign all rights to Fosscord under the AGPLV3 license.
### Desirable Behaviour
- If possible, provide assistance with Fosscord projects to other users.
- Be respectful toward other's opinions and viewpoints.
- Accepting responsibility and apoligising to those affected for our mistakes.
### Prohibited Behaviour
- Sharing leaked, proprietary source code from Discord Inc
- Homophobia, transphobia, etc, misgendering, deadnaming, assuming gender. You should use singular they/them when in doubt.
- Threats of violence
- Harassment
- Spreading hateful, violent, or discriminatory ideologies or conspiracy theories, via media or text (including avatars and nicknames)
- Trolling. Intentionally derailing conversations or producing discussions on non-issues.
- Doxing. Disclosing other's private information without their consent.
- Spamming. This includes sending advertisements, repeatedly sending meaningless content, sending server invites unrequested.
- Sharing media that may cause harm or be triggering to others, such as flashing imagery or gore.
- Undesired automation of services that may lead to a reduction in service quality. For example, API spam of a Fosscord instance.
- Ban evasion. Creation of additional accounts used to join a community after being banned from that community.
- Posting content that is illegal to publish or distribute in Germany.
- Abusing loopholes in this code of conduct, or being in conflict with the goals of this code of conduct.
### Consequences of Violation
- Written warnings, followed by kicks or bans if repeated.
- If a violation is particularly egregious, an immediate kick or ban may be issued.
- Offending content may be removed
- Kicks and bans apply to all communities administered by the Fosscord maintainers group.
### Reporting problems
You may report any violation of this code of conduct to the Fosscord community team directly through Discord, private message or otherwise.
If you believe us to be in violation of this code of conduct, please report it to someone in a higher position, or to many people on the team. Make sure to provide a direct quote from here to be as effective as possible.
### Changes to this document
This code of conduct may be changed in order to enhance clarity and precision at any time. **Notification should be provided**

65
docs/contributing/index.md
View File

@ -1,63 +1,12 @@
# Contributing
By contributing you accept the code of conduct.
!!! info "[Have you read the Code of Conduct?](conduct.md)"
## Code of conduct
## Structure
This is the code of conduct for the Fosscord developer community. It is based on Artemis Lena Code of Conduct by FantasyCookie17. As it is licensed CC0, it may also be used in modified or non-modified form by other communities without permission by the author. Its purpose is to ensure a civilized, tolerant, compassionate, helpful, pluralistic and peaceful style of communication.
Fosscord is written in Typescript and is comprised of 4 main parts:
Fosscord developer community includes Fosscord Github repositories and Fosscord development guild.
Fosscord developers community is administered by the Fosscord maintainers group.
If you contribute to the project in any form (for example through code by a pull request) you guarantee that you have the rights to resign all rights to Fosscord under the AGPLV3 license.
### Desirable behavior
- If possible, providing help with issues other users may have. If it suits the topic of the community, answer it in there, if it does not, try to link to a community where it is more on topic.
- Accepting other opinions, even if you disagree. This does not exclude the possibility to provide arguments for your own opinion.
- Pinging moderators by mentioning their names in chat in the case of rule violations, especially trolling or spamming. While doing so, do not quote or reply to the violator to prevent extra attention by non-moderators.
In order to have your questions resolved more quickly and efficiently, see also: The XY problem, Don't ask to ask, No Hello and How to Ask Smart Questions
### Undesirable behavior
- Talking about things that do not suit the topic of the community. Communities exempt from this rule will mention that in their descriptions.
- Attacking people rather than attacking their arguments (a.k.a. ad hominem).
- Bringing extra attention by people who are not moderators to trolls and spammers.
- Self-censorship for reasons of politeness or similar. As long as you keep it civil and free of insults, it is desirable to discuss issues you have with people directly, rather than letting it build up and later creating drama. It is in the interest of the moderators to make the rooms feel comfortable for a large amount of people, this includes changing their own behavior where necessary and reasonable. If you feel it is better to discuss in a smaller group, ask the person you have an issue with and/or a moderator whether it is fine to invite them to a private chat.
- Making other users feel uncomfortable, for example by nagging them with questions they have stated they do not want to answer.
- Misgendering, deadnaming and assuming gender. Use the singular they/them and inclusive language where possible.
- Not liking the community. If you do, why don't you just leave? You would be causing discomfort to everyone else as well if you did not.
### Prohibited behavior
- Spreading hateful, violent or discriminatory ideologies or conspiracy theories, via images and other media (including avatars) or text (including nicknames), as well as discriminating against any group or person. This includes the use of slurs.
- Spamming. This includes adverts, large amounts of repetitive messages, sending invites to users without asking (invite spam), etc.
- Trolling; intentionally derailing conversations or producing discussions on non-issues.
- Doxing: The disclosure of others' private information without their consent.
- Sharing leaked proprietary source code from Discord Inc.: It is forbidden to share leaked proprietary source code from Discord Inc. Violation may lead to ban and legal consequences.
- Posting media that may cause harm or be triggering to other people. For example, people with photosensitive epilepsy may experience seizures from animations with rapidly changing or flashing colours.
- Actively suppressing opinions of other users.
- Being an undesired bot (bots are undesired if not approved by moderation), or adding an undesired bot to a community.
- Ban evasion (creation of additional accounts to join a community after having been banned from that room).
- If you are a moderator or otherwise have permissions above those of normal users: abusing your permissions for personal motives not compatible with this code of conduct.
- Continued harassment of other users.
- Posting explicit imagery (sexual content, displays of violence, etc.) or unwanted sexual or romantic advances towards other users.
- Posting content that is illegal to publish or illegal to distribute without permission in Germany. The reason is that in certain cases, especially when it comes to copyright, the service provider (who might be us, the fosscord founders), may be held liable, and we do not wish to get into legal trouble.
- Abusing loopholes in this code of conduct, for example doing something that is not explicitly covered by the prohibited behavior, yet is in conflict with the general idea of desirable behavior.
### Consequences of violation
- Undesirable behavior will lead to warnings, and later on, if repeated too often, kicks or bans.
- Prohibited behavior will, in most cases, directly lead to a kick or ban.
- Any kind of violation can lead to removal of the offending content.
- Kicks and bans apply to all communities administrated by Fosscord maintainers group.
If a moderator violates the code of conduct, make sure to point it out to us. This can lead to warnings and demotion of the moderator.
If we violate the code of conduct, no such possibility exists. Thus, it is important to call us out, or make one of our friends call us out. Further steps will then be discussed ad hoc.
### Changes to this code of conduct
This code of conduct may be changed in order to enhance clarity and precision at any time, typically without notification.
// edited by Xenorio and AToska21
- REST HTTP API server
- Websocket Gateway server for realtime communication with clients
- HTTP CDN server for storing user file content.
- `utils` module to separate our database models, schemas, and other things from the above 3 components.

392
docs/contributing/server.md
View File

@ -1,392 +0,0 @@
# Server
## Requirements
Accept the [code of conduct](/contributing/) and follow the server [setup guide](/server/setup/) to setup the development environment.
## Gateway
The Gateway is a WebSocket server that is responsible for listening and emitting events.
For documentation, head over to the [Discord docs](https://discord.dev) as our own documentation is not written yet.
If you want to work on a feature, please comment on the corresponding issue or open a issue so so nobody implements something twice.
For the WebSocket, we use the [ws](https://www.npmjs.com/package/ws) package and we'll write our own packet handler for the individual opcodes and events.
## API
The API is a HTTP REST server that process requests and manipulates the database.
You can find the api documentation [here](/api/).
You can find the Roadmap overview [here](https://github.com/fosscord/fosscord-server/issues/140).
Every route has its own [issue](https://github.com/fosscord/fosscord-api/issues?q=is%3Aopen+is%3Aissue+label%3ARoute).
If you want to work on a feature please comment on the corresponding issue or write us on our [development server](https://discord.gg/ZrnGQP6p3d) so we can assign and discuss it and nobody implements something twice.
### Structure
You can find the [API directory](https://github.com/fosscord/fosscord-server/tree/master/api) in the [fosscord-server](https://github.com/fosscord/fosscord-server) Github repository.
Inside it you can find:
#### Translation
We use [i18next](https://www.i18next.com/) to manage translation/localization in _some_ API Responses.
The `.json` language files are located in `/api/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 [`/api/src/`](https://github.com/fosscord/fosscord-server/tree/master/api/src) and will be compiled to `.js` in the `/api/dist/` directory.
#### Middlewares
All Express [Middlewares](http://expressjs.com/en/guide/writing-middleware.html) are in [`/api/src/middlewares/`](https://github.com/fosscord/fosscord-server/tree/master/api/src/middlewares) and need to be manually loaded by [`/api/src/Server.ts`](https://github.com/fosscord/fosscord-server/blob/master/api/src/Server.ts).
#### Routes
All Express [Router](http://expressjs.com/en/4x/api.html#router) routes are in [`/api/src/routes/`](https://github.com/fosscord/fosscord-server/tree/master/api/src/routes) and are automatically registered based on the file structure.
#### Models
All database TypeORM entities are located in [`/util/src/entities`](https://github.com/fosscord/fosscord-server/tree/master/util/src/entities)
#### Util
All Utility functions are in the directory `/src/util/` and in [`@fosscord/util`](https://github.com/fosscord/fosscord-server/tree/master/util)
## 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.
Only in special cases it should require a third party config value.
The config should be changeable over the [admin dashboard](https://github.com/fosscord/fosscord-server/tree/master/dashboard) and update in realtime without the need to restart the servers.
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.
### Example
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 `Config` from fosscord-server-util:
```js
// at the top of the file import the Config file from /src/util/Config.ts
import { Config } from "@fosscord-server-util";
```
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 { allowNewRegistration } = Config.get().register;
});
```
`Config.get()` returns the current config object and is not expensive at all
### Extending
The default Config is located in [server-util `/src/util/Config.ts`](https://github.com/fosscord/fosscord-server/blob/master/util/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.
## Routes
All routes are located in the directory `/src/routes/` and are loaded on start by a the [lambert-server](https://www.npmjs.com/package/lambert-server) package.
The HTTP API path is generated automatically based on the folder structure, so it is important that you name your files accordingly.
If you want to use URL Params like `:id` in e.g. `/users/:id` you need to use `#` instead of `:` for the folder/filename, because of file naming issues on windows.
`index.ts` files **won't** serve `/api/index` and instead alias the parent folder e.g. `/api/`
Your file needs to default export a [express.Router()](https://expressjs.com/de/4x/api.html#router):
```ts
import { Router } from express;
const router = Router();
export default router;
```
Now you can just use any regular express function on the router variable e.g:
```ts
router.get("/", (req, res) => {});
router.post("/", (req, res) => {});
router.get("/members", (req, res) => {});
```
### Authentication
Every request must contain the authorization header except the `/login` and `/register` route.
You can add additional non-auth routes in [`/src/middlewares/Authentication.ts`](https://github.com/fosscord/fosscord-server/blob/master/api/src/middlewares/Authentication.ts#L5)
To access the user id for the current request use `req.user_id`
### Body Validation
We use a custom body validation logic from lambert-server to check if the JSON body is valid.
To import the function from `/src/util/instanceOf.ts` use:
```ts
import { check } from "/src/util/instanceOf";
```
Now you can use the [middleware](http://expressjs.com/en/guide/using-middleware.html) `check` for your routes by calling check with your Body Schema.
```ts
router.post("/", check(...), (req,res) => {});
```
#### Schema
A Schema is a Object Structure with key-value objects that checks if the supplied body is an instance of the specified class.
```ts
{ id: String, roles: [String] }
```
_Notice if you use e.g. BigInt even if you can't supply it with JSON, it will automatically convert the supplied JSON number/string to a BigInt._
_Also if you want to check for an array of, just put the type inside `[]`._
#### Optional Parameter
You can specify optional parameters if you prefix the key with a `$` (dollar sign) e.g.: `{ $captcha: String }`, this will make the captcha property in the body optional.
#### Limit String length
Additionally import the class `Length` from instanceOf and specify the type by making a new `Length` Object taking following parameters:
```ts
import { Length } from "/src/util/instanceOf";
const min = 2;
const max = 32;
const type = String;
{
username: new Length(min, max, type);
}
```
this will limit the maximum string/number/array length to the `min` and `max` value.
#### Example
```ts
import { check, Length } from "/src/util/instanceOf";
const SCHEMA = {
username: new Length(2, 32, String),
age: Number,
$posts: [{ title: String }],
};
app.post("/", check(SCHEMA), (req, res) => {});
```
#### Throw Errors
If the body validation fails it will automatically throw an error.
The `errors` structure is a key-value Object describing what field contained the error:
```json
{
"code": 50035,
"message": "Invalid Form Body",
"errors": {
"email": {
"_errors": [
{
"message": "Email is already registered",
"code": "EMAIL_ALREADY_REGISTERED"
}
]
},
"username": {
"_errors": [
{
"message": "Must be between 2 - 32 in length",
"code": "BASE_TYPE_BAD_LENGTH"
}
]
}
}
}
```
To manually throw a `FieldError` import `FieldErrors`
```ts
import { FieldErrors } from /src/iltu / instanceOf;
```
To make sure your errors are understood in all languages translate it with [i18next](https://www.i18next.com/translation-function/essentials) and `req.t`.
So after you have checked the field is invalid throw the `FieldErrors`.
```ts
throw FieldErrors(( login: { message: req.t("auth:login.INVALID_LOGIN"), code: "INVALID_LOGIN" }});
```
## Database
### Philosophy
The instance hoster should be able to use any database they want for their specific size and purpose.
That is why we use [typeorm](https://typeorm.io/) for database entities (models) for every data structure we use, because typeorm supports many different database engines.
We use strings for all ids and bitfields (Tho when working with bitfields we convert it to BigInts and pass it to the utility `BitField` class).
### General
Have a look at the [typeorm documentation](https://typeorm.io/) to get familiar with it or watch this [tutorial](https://youtu.be/Paz0gnODPE0).
TypeORM supports MySQL, MariaDB, Postgres, CockroachDB, SQLite, Microsoft SQL Server, Oracle, SAP Hana, sql.js.
### Getting Started
Import the entity you want to select, manipulate, delete or insert from `@fosscord/util`
[List of all entities](https://github.com/fosscord/fosscord-server/blob/master/util/src/entities/index.ts): `Application, Attachment, AuditLog, Ban, BaseClass, Channel, Config, ConnectedAccount, Emoji, Guild, Invite, Member, Message, RateLimit, ReadState, Recipient, Relationship, Role, Sticker, Team, TeamMember, Template, User, VoiceState, Webhook`
### Example database query
```ts
import { Guild } from "fosscord-server-util";
await new Guild({ ... }).save(); // inserts a new guild or updates it if it already exists
const guild = await Guild.findOne({ id: "23948723947932" }).exec(); // searches for a guild
await Guild.delete({ owner_id: "34975309473" }) // deletes all guilds of the specific owner
```
### Entities
The typeorm database entities are located in [`util/src/entities/`](https://github.com/fosscord/fosscord-server/tree/master/util/src/entities).
To add your own database entity, create a new file, export the model and import/export it in [`util/src/entities/index.ts`](https://github.com/fosscord/fosscord-server/tree/master/util/src/entities/index.ts).
#### Example entity
```ts
@Entity("users")
export class User extends BaseClass {
// id column is automatically added by BaseClass
@Column()
username: string;
@JoinColumn({ name: "connected_account_ids" })
@OneToMany(
() => ConnectedAccount,
(account: ConnectedAccount) => account.user
)
connected_accounts: ConnectedAccount[];
static async getPublicUser(user_id: string, opts?: FindOneOptions<User>) {
return await User.findOneOrFail(
{ id: user_id },
{
...opts,
select: [...PublicUserProjection, ...(opts?.select || [])],
}
);
}
}
```
## Emit Events
Most Routes modify the database and therefore need to inform the clients with events for data changes.
Events are either stored locally if the server was started through the bundle or in RabbitMQ and are distributed to the gateway servers.
You can find all events on the [discord docs page](https://discord.com/developers/docs/topics/gateway#commands-and-events) and in [`util/src/interfaces/Event.ts`](https://github.com/fosscord/fosscord-server/blob/master/util/src/interfaces/Event.ts).
To emit an event import the `emitEvent` function from `@fosscord/util`
```ts
import { emitEvent } from "../../../util/Event";
```
You need to specify whom you want to send the event to, to do that either pass `guild_id`, `user_id` or `channel_id`.
Additionally you need to set the [eventname](https://github.com/fosscord/fosscord-server/blob/master/util/src/interfaces/Event.ts#L539) e.g. `GUILD_DELETE`.
```ts
{
guild_id?: bigint; // specify this if this event should be sent to all guild members
channel_id?: bigint; // specify this if this event should be sent to all channel members
user_id?: bigint; // specify this if this event should be sent to the specific user
event: string; // the EVENTNAME, you can find all gateway event names in the @fosscord/util Events file
data?: any; // event payload data
}
```
For easy intellisense, annotate the parameter with the corresponding [Event interface](https://github.com/fosscord/fosscord-server/blob/master/util/src/interfaces/Event.ts) from `@fosscord/util`:
```ts
import { GuildDeleteEvent } from "@fosscord/util";
emitEvent({...} as GuildDeleteEvent);
```
### Example
Putting it all together:
```ts
await emitEvent({
user_id: "3297349345345874",
event: "GUILD_DELETE",
data: {
id: "96784598743975349",
},
} as GuildDeleteEvent);
```
## Permissions
To get the permission for a guild member import the `getPermission` from `fosscord-server-util`.
```ts
import { getPermission } from "fosscord-server-util";
```
The first argument is the user_id the second the guild_id and the third an optional channel_id.
```ts
const permissions = await getPermission(user_id: string, guild_id: string, channel_id?: string)
const permissions = await getPermission("106142653265366125", "4061326832657368175")
```
### Example
```ts
const perms = await getPermission(req.userid, guild_id);
// preferred method: Use this if you want to check if a user lacks a certain permission and abort the operation
perms.hasThrow("MANAGE_GUILD") // will throw an error if the users lacks the permission
if (perms.has("MANAGE_GUILD")) {
...
}
```

57
docs/contributing/ui.md
View File

@ -1,57 +0,0 @@
# UI Framework
- see: [@fosscord/ui](https://www.npmjs.com/package/@fosscord/ui)
## Requirements
You should be familiar with:
- [Git](https://git-scm.com/)
- [NodeJS](https://nodejs.org/)
- [SCSS](https://sass-lang.com/)
## Getting Started
```bash
git clone https://github.com/fosscord/fosscord-ui
cd fosscord-ui
```
```bash
npm install
npm run scss
```
_Open `./test/index.html` to see the test page._
## Writing a component
> text inside of <> has to be replaced by the corresponding values
1. create a file named like the component you're creating in
`test/<component>.html` and `scss/<component>.scss`
2. copy the content of `test/template.html` to `test/<component>.html` and
replace the `<h1>` content with the components name
3. source the created `test/<component>.html>` in `test/index.html` as follows:
_append the following to `scss/index.scss` to the div with the class
`"grid"`_
```html
<a
class="Link"
href="<component>.html"
class="text link">
<component>
</a>
```
4. source the created `scss/<component>.scss` in `scss/index.scss` as follows:
_append the following to `scss/index.scss`_
```scss
...
@import "<component>.scss";
```

26
docs/faq.md
View File

@ -1,26 +0,0 @@
# Frequently Asked Questions
## Can I get free Nitro?
We Fosscord developers and server administrators can't grant you free nitro at discord.com.
A Fosscord instance administrator may choose to grant you free nitro or its equivalent powers in its own instance.
Do not beg for free Nitro in Fosscord Github repository, or in Fosscord Official Development Guild.
## Why are we reimplementing and extending the Discord protocol?
1. Despite its API complexity, underlying working principle of the protocol is quite simple. No complex conflict resolution like, say, Matrix.
2. People want persistent decentralised chats. Also to speak, Discord's event ordering is strictly linear, which again simplifies server, client and bot development.
3. Discord protocol has event authorisation finality, which simplifies the server design.
4. The server does most of the heavy lifting, which allows for more easy client and bot development.
5. There are many bots for Discord that can be modified to use a Fosscord instance.
6. We love free software. Hence our server is licensed under Affero GPLv3, and some other parts are licensed under GPLv3.
7. We embrace and love third party clients. The more clients there are, the harder for Discord Inc. to shut down this project.
8. Discord's security model is based on the enforcement of well-formedness throughout the protocol. And this is great for achieving security without an extensive lock-in.
## By when will the version/feature X have been available?
As always, we don't give ETAs; because users tend to reinterpret ETAs as committed due dates.
## When is the next stable version going to be released?
When it's ready.

63
docs/index.md
View File

@ -1,53 +1,26 @@
# Home
Just wanna get to setup instructions? Click [here](server/setup.md)!
!!! info "Want to skip to the server installation guide? [Click here](setup/server)"
### What is Fosscord?
!!! info "Interested in contributing? We'd love to have you on board! [Click here](contributing)"
Fosscord is a free open source self-hostable discord compatible chat, voice and video platform.
## What is Fosscord?
## Philosophy
Fosscord is a Discord.com server implementation and extension,
with the goal of complete feature parity with Discord.com,
all while adding some additional goodies, security, privacy, and configuration options.
Fosscord aims to be a full one-on-one clone of Discord, adding more features
that can be used as a replacement for the official client and still connect to
discord.com and host private Fosscord server instances.
Fosscord allows you to host a complete, Discord.com-compatible chat service
with complete control over it's content, usage, security, configuration, and featureset.
Being Discord.com-compatible, all existing clients, bots, and applications written for
Discord.com can be used on any Fosscord instance, which we believe will be immensely useful
in any transition process between services.
Fosscord aims to give the best possible user experience, while being backwards
compatible to Discord's features and adding new ones/improving old ones while
maintaining the user privacy with end-to-end encryption support.
As Fosscord is an entirely separate service from Discord.com, it means a Fosscord server by itself **cannot**
access private data controlled by Discord.com. You **cannot** use a Fosscord server to chat with your friends on Discord.com.
You also **cannot** use a Fosscord server to grant premium ("Nitro") features to a Discord.com account (although you can grant these to a Fosscord account).
The client can connect to multiple server instances without the need to open it
multiple times.
The client should be extensible through a secure Plugin and Theme System with
own store.
The server should be extensible through bots, just like discord without the need
to change anything except the api endpoint.
The project is open source so everyone can have a look what's going on under the
hood and can be maintained and expanded by the community.
Everything is configurable in the server config and everyone can add their own
features, so that it is not opinionated.
### Concept
<img src="assets/architecture.png" alt="Architecture">
### Why backwards compatible to Discord?
- Benefit from the large user base of discord -> more users, making the switch
easier for new users & keeping workflows intact and easily migrating existing discord bots
- No disadvantage for the users who use fosscord, so that they can still
communicate with all their peers who use discord
- Discord has already built a great and stable protocol _(don't reinvent the
wheel)_
- The community can extend and customize their clients and servers by
self-hosting them and developing and installing addons
## Support
[Discord server](https://discord.gg/ZrnGQP6p3d)
Once we are finished, we'll host our own instance to host the support server.
Our goal is to achieve complete feature parity with Discord.com, as well as
implement additional security, privacy, and other useful features serverside.
In addition to our server software, we aim to create Fosscord-aware clients that can be used to connect
to multiple Fosscord-compatible instances - including Discord.com - with rich theming and plugin support.

46
docs/resources.md
View File

@ -1,46 +0,0 @@
## Links
- [Documentation](https://docs.fosscord.com)
- [Roadmap](https://fosscord.notion.site/2c7fe9e73f9842d3bab3a4912dedd091) (Notion to-do board synced with GitHub issues)
- [Status](https://status.fosscord.com/) (Status page of the official fosscord instance)
- [GitHub](https://github.com/fosscord/) (GitHub organization)
- [OpenCollective](https://opencollective.com/fosscord) (Financially support the project to cover server costs and other expenses)
- [Discord server](https://discord.gg/ZrnGQP6p3d) (for support & organization (If we are finished we'll host our own support server))
- [Tor Hidden Service](http://7jexqzsbqndcsh6y7hybtaf5us5vt7mya7hi4fbi2tid6zazno3h44qd.onion/) (Official Fosscord instance on TOR)
## Project structure
Fosscord consists of many repositories, which together make up the client and server:
### Server
- **[fosscord-server](https://github.com/fosscord/fosscord-api) is the complete Fosscord Server** and it
Contains:
- [api](https://github.com/fosscord/fosscord-server/tree/master/api) a HTTP REST server
- [gateway](https://github.com/fosscord/fosscord-server/tree/master/gateway) a WebSocket Gateway server
- [rtc](https://github.com/fosscord/fosscord-server/tree/master/rtc) a _C++_ webRTC server for voice and video sharing.
- [webRTC-server](https://github.com/fosscord/fosscord-server/tree/master/webrtc-server) a _javascript_ webRTC server for voice and video communication
- [dashboard](https://github.com/fosscord/fosscord-server/tree/master/dashboard) An admin dashboard for the server (analytics, settings, administration, trust & safety)
- [util](https://github.com/fosscord/fosscord-server/tree/master/util) contains all shared logic like Database Models, Utility functions...
- [cdn](https://github.com/fosscord/fosscord-server/tree/master/cdn) is the content-delivery-content (CDN) that stores user uploaded images.
### Client
- [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-client](https://github.com/fosscord/fosscord-client) is the official (react)-native Fosscord client.
- ~~[fosscord-web-client](https://github.com/fosscord/fosscord-web-client) was an effort to develop a fosscord web client.~~ (Discontinued)
- ~~[react-native-withcss](https://github.com/fosscord/react-native-withcss) CSS support for react native~~ (Discontinued)
- ~~[css-mediaquery](https://github.com/fosscord/css-mediaquery) CSS media query support for react native~~ (Discontinued)
#### Others
- [fosscord-docs](https://github.com/fosscord/fosscord-docs) Documentation of Fosscord
- [fosscord-landingpage](https://github.com/fosscord/fosscord-landingpage) represents and explains the project.
- [fosscord.js](https://github.com/fosscord/fosscord.js) A powerful JavaScript library for interacting with the Fosscord API
- [fosscord.js-builders](https://github.com/fosscord/fosscord.js-builders) A collection of builders that you can use when creating your bot.
- [fosscord.py](https://github.com/fosscord/fosscord.py) An API wrapper for Fosscord written in Python.
- [docker](https://github.com/fosscord/docker) 🐳 Fosscord's Docker images and composing

2
docs/api/routes.md → docs/routes.md
View File

@ -1,3 +1,3 @@
# Routes
# API Routes
!!swagger-http https://raw.githubusercontent.com/fosscord/fosscord-server/master/api/assets/openapi.json!!

64
docs/server/configuration.md
View File

@ -1,64 +0,0 @@
# Configuration
The configuration of Fosscord is located inside the database, under the ``config`` table. Some configuration is also done via [environment variables](env.md)
## Editing
In order to edit your configuration, you will need to manually open your database with special tools.
### Tools
#### Sqlite
- [DBeaver](https://dbeaver.io)
- [SqliteBrowser](https://sqlitebrowser.org)
#### PostgreSQL
- [DBeaver](https://dbeaver.io)
- [pgAdmin](https://www.pgadmin.org)
#### MySQL/Mariadb
- [DBeaver](https://dbeaver.io)
## Options
This list may be incomplete.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| gateway_endpointClient | string | null | The gateway endpoint that gets delivered to the client |
| gateway_endpointPrivate | string | null | The gateway endpoint that is used internally to communicate between gateway servers |
| gateway_endpointPublic | string | null | The gateway endpoint that is publicly used by bots |
| cdn_endpointPublic | string | "/" | The cdn endpoint that is served in message attachments |
| cdn_endpointClient | string | null | The cdn endpoint that is used by clients |
| cdn_endpointPrivate | string | "http://localhost:3001" | The cdn endpoint that is used internally to upload images from the api to the cdn. |
| general_instanceId | string | _auto generated_ | Unique identifier for the Fosscord instance |
| limits_user_maxGuilds | number | 100 | Maximum number of guilds the user is allowed to create and join |
| limits_user_maxUsername | number | 32 | Maximum number of characters for a username |
| limits_user_maxFriends | number | 1000 | Maximum number of friends a user can have |
| limits_guild_maxRoles | number | 250 | Maximum number of roles a guild can have |
| limits_guild_maxEmojis | number | 50 | Maximum number of custom emojis a guild can have |
| limits_guild_maxMembers | number | 250000 | Maximum number of members a guild can have |
| limits_guild_maxChannels | number | 50 | Maximum number of channels a guild can have |
| limits_guild_maxChannelsInCategory | number | 50 | Maximum number of channels a category can contain |
| limits_guild_hideOfflineMember | number | 1000 | Amount of members when a guild is considered large and offline members are hidden |
| limits_message_maxCharacters | number | 2000 | Maximum length of characters a message can have |
| limits_message_maxTTSCharacters | number | 200 | Maximum length of characters a text to speech message can have |
| limits_message_maxReactions | number | 20 | Maximum number of reactions a message can have |
| limits_message_maxAttachmentSize | number | 8388608 | Maximum size a message attachment can have in bytes |
| limits_message_maxBulkDelete | number | 100 | Maximum amount of messages that can be deleted per bulk delete command |
| limits_channel_maxPins | number | 50 | Maximum amount of pinned messages a channel can have |
| limits_channel_maxTopic | number | 1024 | Maximum amount of characters a channel topic description can have |
| limits_channel_maxWebhooks | number | 10 | Maximum amount of webhooks a channel can have |
| limits_rate_disabled | boolean | false | Check to enable rate limits |
| limits*rate* | | _TODO_ | |
| security_autoUpdate | boolean | true | Check if updates should automatically be searched for and non destructively be installed |
| security_requestSignature | string | _auto generated_ | Request signature that is used internally to sign requests |
| security_jwtSecret | string | _auto generated_ | JSON web token secret to sign and verify jwt tokens |
| security_forwardedFor | string | null | Header name that is used to retrieve the real ip of a request e.g. X-Forwarded-For or CF-Connecting-IP |
| security_captcha_enabled | boolean | false | Check to enable captchas |
| security_captcha_service | string | null | Captcha provider, one of: "recaptcha", "hcaptcha" |
| security_captcha_sitekey | string | null | Captcha provider site key |
| security_captcha_secret | string | null | Captcha provider secret to check if the user supplied captcha result is correct |
| security_ipdataApiKey | string | _public key_ | IPdata.co api key to check if a register ip address is using proxies |
| login_requireCaptcha | boolean | false | Check to require captchas to login |

23
docs/server/database.md
View File

@ -1,23 +0,0 @@
# Database
By default, Fosscord uses Sqlite as its database. But doing this in a production environment is highly discouraged for performance reasons.
You can change the database Fosscord uses by editing the ``DATABASE`` environment variable. This is further explained [here](env.md)
## Connection URL
The connection URL you need to specify looks like this:
```
[type]://[username]:[password]@[address]/[dbname]
```
Replace the variables marked with ``[]`` with the following:
| Name | Description |
| --- | --- |
| [type] | The type of database to use, either ``mariadb`` or ``postgres`` |
| [username] | The name of a user with access to the database |
| [password] | The password for the user |
| [address] | The network address the database is located at, most likely ``localhost`` |
| [dbname] | The name of the database to use |

38
docs/server/env.md
View File

@ -1,38 +0,0 @@
# Environment Variables
Some configuration is done via environment variables. If you can't find what you're looking for here, try [database configuration](configuration.md)
## Editing
In order to edit environment variables, just create a file called ``.env`` in ``bundle/``. In there, you can declare variables in the format ``VARIABLE=value``.
If you want to globally assign variables, use `export` on Linux or `set` on Windows.
For example: `export THREADS=8`.
Note that this only sets variables for the current shell. To make them run by default on opening any shell, add your commands to ``/etc/profile`` on Linux or use ``setx`` instead of ``set`` on Windows.
## Options
This list may be incomplete.
| Name | Description |
| --- | --- |
| THREADS | Amount of threads/workers to use |
| DATABASE | Connection URL of the database |
## Example
This list may be incomplete.
| Name | Description |
| --- | --- |
| WORK_DIR | /srv/fosscord-server |
| DEV_MODE | 0 |
| THREADS | 8 |
| DATABASE | db://username:password@db/dbname |
| STORAGE_LOCATION | /srv/fosscord-server/data/files/ |
| HTTP_PORT | 3001 |
| WS_PORT | 3002 |
| CDN_PORT | 3003 |
| RTC_PORT | 3004 |
| ADMIN_PORT | 3005 |

43
docs/server/hosting.md
View File

@ -1,43 +0,0 @@
# Hosting
Many users are confused on where to host their Fosscord instances. This guide will show you multiple hosting methods, and tell you what works and what does not.
As a rule of thumb: Free hosting methods generally do not work!
## <span style="color:green">Recommended Methods</span>
### Dedicated Servers
A dedicated server is the most classic hosting solution. It is an actual, physical machine that you get completely for yourself. They are more expensive than a typical VPS for example, but give you the most control, down to what exact hardware you want to use.
| Pro | Contra |
|---|---|
| Full Control | More expensive |
| You get the full potential of your server | No dynamic resources |
**Recommended providers:** [ServerBlaze](https://serverblaze.eu/) (Sponsor), [Hetzner](https://hetzner.com)
### Virtual Private Servers
A Virtual Private Server, or VPS for short, is a virtual machine that runs on a larger dedicated server. This makes a VPS cheaper than a dedicated server, as providers can rent out multiple VPS's per server. It also allows you to dynamically change the resources your server is getting, if your provider supports that.
| Pro | Contra |
|---|---|
| Affordable | Virtualized |
| Dynamic Resources | Hardware is shared with others |
**Recommended providers:** [Google Cloud](https://cloud.google.com/), [AWS](https://aws.amazon.com/), [Azure](https://azure.microsoft.com)
### Selfhosting
Depending on your electricity prices, this may be the cheapest option. Just use any machine that you don't actively need as a server, and run it at home! This could be an old PC, a [Raspberry Pi](https://www.raspberrypi.org/), actual server hardware, or technically even a phone. This gives you the most control possible, and also allows you to breathe some life into old devices!
**Note:** Publicly hosting a service from your internet connection reveals your IP address to the public. If you do not want that, you can look into services like [Cloudflare](https://www.cloudflare.com/).
| Pro | Contra |
|---|---|
| The most control | A lot of work |
| Repurpose old devices | Risk of DDOS attacks etc |
## <span style="color:red">Unsupported Methods</span>
- Specialized website hosting services, that don't give you root access to a server
- Online code collaboration sites like [**replit**](https://replit.com) or [**glitch**](https://glitch.com)
- Hosting with ngrok - you will not be able to use attachments (send files/images) as you do not have a static domain name

6
docs/server/index.md
View File

@ -1,6 +0,0 @@
# Server
## [Setup](setup.md)
## [Configuration](configuration.md)
## [Environment Variables](env.md)
## [Reverse Proxy/SSL](ssl.md)

66
docs/server/setup.md
View File

@ -1,66 +0,0 @@
# Setup
<!-- ### [Download](https://github.com/fosscord/fosscord-server/releases)
This is the stable fosscord-server release.
Download the server release from [GitHub](https://github.com/fosscord/fosscord-server/releases) for your operating system. (Size ~80mb)
Double click the file to start the server. (The first time it takes longer as it needs to setup the server)
You can now access it on [http://localhost:3001](http://localhost:3001). -->
### With Terminal
This is the latest bleeding edge version of fosscord-server, which may have bugs.
#### Requirements
- [NodeJS](https://nodejs.org) v14+
- [Python](https://python.org) 3
- (Only on Linux) ``gcc`` and ``g++`` | Packaged with `build-essential` on Debian/Ubuntu and `base-devel` on Arch
- (Only on Windows) [Visual Studio](https://visualstudio.microsoft.com/) with the C++ package
!!! info "Make sure python can be executed by just running `python`"
#### Setup
Open a shell/terminal and execute these commands:
```
git clone https://github.com/fosscord/fosscord-server
cd fosscord-server
cd bundle
npm run setup
npm run start:bundle
```
You can now access Fosscord on [http://localhost:3001](http://localhost:3001)
#### Updating
To update Fosscord, execute these commands:
!!! warning "This reverts any edited files"
```
git reset --hard HEAD
git pull
npm run setup
npm run start:bundle
```
### With Docker
!!! failure "Not Supported Currently"
Avoid using Docker build until further notice. The current build is faulty and will not build correctly. Instead, install using the terminal in the section "With Terminal".
Optionally, if you want to use Docker:
```
git clone https://github.com/fosscord/fosscord-server
cd fosscord-server
docker-compose up -d
```
You can now access Fosscord on [http://localhost:3001](http://localhost:3001)

29
docs/server/ssl.md
View File

@ -1,29 +0,0 @@
# Reverse Proxy/SSL
If you're running a production instance of Fosscord, it is **strongly** recommended to use SSL (better known as https), which you can achieve by using a reverse proxy.
A reverse proxy not only gives your instance SSL support, but also allows you to run it alongside other web services behind the same port!
## Proxies
There are multiple reverse proxies you can use, the most popular being [Nginx](https://nginx.org) and [Traefik](https://traefik.io/traefik/).
Another popular solution that allows easy management via a webinterface and is based on Nginx is [NginxProxyManager](https://nginxproxymanager.com/).
## Setup
Choose your preferred reverse proxy, and install it using the respective setup instructions.
Then, configure it to forward traffic from your domain (or a subdomain) to the port your Fosscord instance runs on (3001 by default).
To be able to use SSL, you will need an SSL certificate. If you're using NginxProxyManager, you just need to enable SSL support and your proxy will automatically generate and set up certificates for you. Otherwise, you will need to set up [Certbot](https://certbot.eff.org).
## Guides
[Nginx](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/)
[NginxProxyManager](https://nginxproxymanager.com/guide/#quick-setup)
[Traefik](https://doc.traefik.io/traefik/getting-started/install-traefik/)
[Certbot](https://certbot.eff.org/instructions)

21
docs/server/systemd.md
View File

@ -1,21 +0,0 @@
# Systemd Service
If you want to run Fosscord as a systemd service, simply put this in ``/etc/systemd/system/fosscord.service``:
```
[Unit]
Description=<your description>
[Service]
User=<your user>
WorkingDirectory=<fosscord bundle directory>
ExecStart=npm run start:bundle
Restart=always
[Install]
WantedBy=multi-user.target
```
Then, execute ``sudo systemctl start fosscord`` from your terminal.
If you want to automatically run Fosscord on boot, execute ``sudo systemctl enable fosscord``

61
docs/setup/bots/index.md Normal file
View File

@ -0,0 +1,61 @@
# Bots and Applications
Fosscord is backwards-compatibile with Discord.com, and so all
existing bots and applications designed for Discord.com should work with relatively easily
when connected to a Fosscord instance instead.
The Discord Developer Panel is available at /developers, and allows you all the same functionality
to create bots and applications on a Fosscord instance as Discord.com.
## Bot Libraries
### Discord.js
The `Client` class constructor accepts a `http` object, which you can use to change
the endpoints used.
```js
const { Client } = require("discord.js");
const client = new Client({
http: {
version: 9,
api: "https://api.fosscord.com",
cdn: "https://cdn.fosscord.com",
invite: "https://fosscord.com/invite",
},
});
client.login("your token here");
```
### Discord.py
```py
import discord
discord.http.Route.BASE = "https://api.fosscord.com"
client = discord.Client()
client.run('your token here')
```
### JDA
```java
import java.lang.reflect.*;
import net.dv8tion.jda.internal.requests.*;
public static void main(String[] args) {
JDA jda = JDABuilder.createDefault("your token here").build();
Field field = Requester.class.getDeclaredField("DISCORD_API_PREFIX")
field.setAccessible(true);
Field modifiers = Field.class.getDeclaredField("modifiers");
modifiers.setAccessible(true);
modifiers.setString(field, field.getModifiers() & ~Modifier.FINAL);
field.set(null, "https://api.fosscord.com");
}
```

0
docs/setup/index.md Normal file
View File

19
docs/setup/server/configuration/env.md Normal file
View File

@ -0,0 +1,19 @@
# Environment Variables
Below is a list of environment variables used by Fosscord.
You can set environment variables easily by creating an `.env` file
in the `fosscord-server` folder, with the format `NAME=VALUE` with each on new lines.
| Name | Value | Description |
| ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------- |
| THREADS | number | Number of threads to run Fosscord on when using bundle. Make sure you've enabled RabbitMQ if using more than one |
| PORT | number | Port to listen on. Used by all components, including bundle. If using bundle, all components run under the same port |
| DATABASE | string | Database connection string. Defaults to SQlite3 at project root |
| CONFIG_PATH | string | File path for JSON config, if not using `config` db table |
| WS_LOGEVENTS | boolean | If set, log websocket events from gateway |
| CDN | string | Lowest priority value for public CDN annoucements |
| GATEWAY | string | Lowest priority value for public gateway annoucements |
| STORAGE_LOCATION | string | CDN storage location. File path or S3 bucktet |
| STORAGE_PROVIDER | "s3" or "file" | CDN storage provider |
| STORAGE_BUCKET | string | S3 bucket name |
| STORAGE_REGION | string | S3 storage region |

8
docs/setup/server/configuration/guildFeatures.md Normal file
View File

@ -0,0 +1,8 @@
# Guild Features
Guild features as special modifiers assigned to guilds for additional functionality.
In Fosscord, guild features are stored in the `features` column of the `guilds` table as a comma separated list, with no spaces.
For example, `ANIMATED_ICON,BANNER,DISCOVERABLE`.
A list of all available guild features is available [here](https://gist.github.com/Techy/ecc60b12e94f8fc8185f09b82aa91dd2)

11
docs/setup/server/configuration/index.md Normal file
View File

@ -0,0 +1,11 @@
# Configuration
Fosscord's configuration is done through the `config` table of your database.
The table schema consists of two columns `key` and `value`, where `value` is a JSON value.
For now, you can update this through SQL manually or a GUI database editor such as
[DBeaver](https://dbeaver.io/) or [SQLite Browser](https://sqlitebrowser.org/) if using SQLite.
The available configuration options, as 20/12/22 are listed below.
If a key is prepended by `?`, it is optional. The `?` is not a part of the key name.
TODO: All available config options.

8
docs/setup/server/configuration/userFlags.md Normal file
View File

@ -0,0 +1,8 @@
# User Flags
User flags describe special properties of users, including whether they are staff, a verified bot, a bug hunter, etc.
You can change a user's flags by setting the `public_flags` value in the `users` table.
You can assign multiple flags by simply summing the respective values.
A list of all user flags is available [here](https://github.com/Delitefully/DiscordLists/blob/master/flags.md)

12
docs/setup/server/database.md Normal file
View File

@ -0,0 +1,12 @@
# Database
By default, Fosscord will use SQLite. SQLite is nice for testing or development,
but if you plan to run an instance with any sort of demand, you'd best set up a more Proper™ database
such as MariaDB or Postresql, which are both popular choices within the community.
We won't go into the setup of these servers here, given the scope of our documentation,
but to configure Fosscord to use your new, shiny database, simply set the `DATABASE` [environment variable](configuration/env.md)
to your new database connection string.
Usually, such a string will look something like
`type://username:password@your-IP/databaseName`

41
docs/setup/server/imagor.md Normal file
View File

@ -0,0 +1,41 @@
# Imagor
[Imagor](https://github.com/cshum/imagor) is a "fast, secure image processing server"
used by Fosscord for external image resizing, primarily by embeds from other websites when linked in a message.
If left unused, Fosscord will simply not provide a proxy_url for clients, which may leave external images unavailable
or cause the client to download directly from the image host.
## Dependencies
- [Docker](https://www.docker.com/)
## Setup
To setup Imagor for Fosscord, first grab the `security_requestSignature` config value from Fosscord's database,
and create a `imagor.env` file somewhere safe, with the following content.
```
IMAGOR_SECRET=[security_requestSignature value]
```
You can now start Imagor with
```bash
docker run --env-file ./imagor.env -p 8000:8000 shumc/imagor
```
`8000` here is our port. Make sure that it'd available to people outside your network.
If you're using a reverse proxy such as Nginx for Fosscord already, you could add this to your config's `server` block
```nginx
location /media {
proxy_pass http://127.0.0.1:8000;
}
```
Along with any additional config you already have, of course.
Alternative (and perhaps the better choice) would be to create a new domain, say `media.whatever.com` specifically for Imagor.
Our last step is to simply tell Fosscord about Imagor. Just set the `cdn_imagorServerUrl` config value to your public endpoint for Imagor, wrapped in quotes.
Congrats! After a restart, you've now got Imagor resizing your images!

53
docs/setup/server/index.md Normal file
View File

@ -0,0 +1,53 @@
# Server Setup
Fosscord-server setup ranges in difficulty depending on how you want to configure your system.
This page provides a minimal setup guide to get you up and running,
you should check out the other pages on this site to take your instance to the next level.
For this guide, we assume you're familar with the terminal.
We do **not** recommend or support running Fosscord using services such as Ngrok, Heroku or other 'free' hosting providers.
You **must** have access to a terminal for this guide.
## Dependencies
- [Git](https://git-scm.com/)
- [NodeJS](https://nodejs.org). Version 16+
- [Python](https://www.python.org/). Version 3+. Make sure this is executable via `python` in your terminal.
- On Linux: `gcc`/`g++`. Packaged with `build-essential` on Debian/Ubuntu and `base-devel` on Arch.
- On Windows: [Visual Studio](https://visualstudio.microsoft.com/) (**NOT** VSCode) with the C++ development package.
## Setup
In your terminal:
```bash
# Download Fosscord
git clone https://github.com/fosscord/fosscord-server.git
# Navigate to project root
cd fosscord-server
# Install javascript packages
npm i
# Build and generate schema. Separately, they are `build` and `generate:schema`.
npm run setup
# Syncronise database. Be careful running this on existing databases,
# as you may incur dataloss.
npm run sync:db
# Start the bundle server ( API, CDN, Gateway in one )
npm run start
```
If all went according to plan, you can now access your new Fosscord instance at [http://localhost:3001](http://localhost:3001)! Congrats!
## Now what?
Well, now you can configure Fosscord to your liking!
- [Skip to server configuration](configuration)
- [Skip to reverse proxy / SSL](reverseProxy.md)
- [Skip to security](security.md)

51
docs/setup/server/reverseProxy.md Normal file
View File

@ -0,0 +1,51 @@
# Reverse Proxy
## NGINX
Generally, our community sets up Fosscord instances behind NGINX, a powerful reverse proxy.
Below is an example NGINX config. On Ubuntu, you can put this in `/etc/nginx/sites-available/fosscord`,
and enable it with `ln -s /etc/nginx/sites-available/fosscord /etc/nginx/sites-enabled/` and `systemctl restart nginx`
```nginx
server {
# Change server_name
server_name fosscord.example.com;
listen 80;
location / {
# do NOT change this
proxy_pass http://127.0.0.1:3001;
proxy_set_header Host $host;
proxy_pass_request_headers on;
add_header Last-Modified $date_gmt;
add_header Cache-Control 'no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0';
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Host $remote_addr;
proxy_no_cache 1;
proxy_cache_bypass 1;
# This is important. It allows Websocket connections through NGINX.
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
## SSL
After you've set up NGINX, it's very simple to also set up SSL using `certbot`.
On Ubuntu:
```bash
sudo apt install certbot python3-certbot-nginx
certbot --nginx
```
You should be asked various questions, such as which site you want to enable SSL for.
Afterwhich, you should now have a SSL secured Fosscord instance!
But wait! There's more, actually. If you have changed your `gateway_endpointPublic`
or `cdn_endpointPublic` addresses, you'll probably have to update those to use the new protocol (`https` or `wss`).

0
docs/setup/server/security/captcha.md Normal file
View File

11
docs/setup/server/security/index.md Normal file
View File

@ -0,0 +1,11 @@
# Security
There are various security measures available to instance owners.
## [Rights](rights.md)
## [Captchas](captcha.md)
## [Registration Tokens](regTokens.md)
## [Rate Limits](limits.md)

1
docs/setup/server/security/limits.md Normal file
View File

@ -0,0 +1 @@
# Rate Limiting

1
docs/setup/server/security/regTokens.md Normal file
View File

@ -0,0 +1 @@
# Registration Tokens

69
docs/setup/server/security/rights.md Normal file
View File

@ -0,0 +1,69 @@
# Rights
Rights are instance-wide, per-user permissions for everything you may perform on the instance,
such as sending messages, editing messages, or shutting down the server.
You may modify a users rights by editing the `rights` column in the `users` table.
The rights value is a bitfield string. To grant multiple rights you must add their values together.
For example, to grant `CREATE_GUILDS` and `SEND_MESSAGES`, set their `rights` to
`(1 << 15) = 32768` +
`(1 << 25) = 33554432` =
`33587200`
The default rights value given to users (set through the `register_defaultRights` config value)
is generated through the `npm run generate:rights` script.
Below is a list of all available rights
| Right | Value | When enabled |
| ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPERATOR` | 1 << 0 | All rights |
| `MANAGE_APPLICATIONS` | 1 << 1 | Ability to alter or remove others' applications |
| `MANAGE_GUILDS` | 1 << 2 | Same as the per-guild `MANAGE_GUILD` permission, but applies to all guilds and DM channels, can join any guild without invite |
| `MANAGE_MESSAGES` | 1 << 3 | Can delete or edit any message they can read |
| `MANAGE_RATE_LIMITS` | 1 << 4 | Add, change, define rate limits of other users, can also grant others `BYPASS_RATE_LIMITS` when combined with `BYPASS_RATE_LIMITS` and `MANAGE_USERS` |
| `MANAGE_ROUTING` | 1 << 5 | Create, alter, enable, disable custom message routing rules in any channel/guild |
| `MANAGE_TICKETS` | 1 << 6 | Respond to or resolve other users' support tickets |
| `MANAGE_USERS` | 1 << 7 | Create, alter, remove, ban users; create, modify, remove user groups |
| `ADD_MEMBERS` | 1 << 8 | Can manually add members into their guilds and group DMs |
| `BYPASS_RATE_LIMITS` | 1 << 9 | Makes the user exempt from all rate limits |
| `CREATE_APPLICATIONS` | 1 << 10 | Can create, edit, remove own applications |
| `CREATE_CHANNELS` | 1 << 11 | Can create guild channels and custom channels |
| `CREATE_DMS` | 1 << 12 | Can create 1:1 DMs (a user without `SEND_MESSAGES` cannot be added however) |
| `CREATE_DM_GROUPS` | 1 << 13 | Can create group DMs (a user without `SEND_MESSAGES` cannot be added however) |
| `CREATE_GUILDS` | 1 << 14 | Can create guilds |
| `CREATE_INVITES` | 1 << 15 | Can create mass invites in the guilds that they have `CREATE_INSTANT_INVITE` |
| `CREATE_ROLES` | 1 << 16 | Can create roles and per-guild or per-channel permission overrides in the guilds that they have permissions |
| `CREATE_TEMPLATES` | 1 << 17 | Can create templates for guilds, custom channels and channels with custom routing |
| `CREATE_WEBHOOKS` | 1 << 18 | Can create webhooks in the guilds that they have permissions |
| `JOIN_GUILDS` | 1 << 19 | Can join guilds by using invites or vanity names |
| `PIN_MESSAGES` | 1 << 20 | Can modify the pinned messages in the guilds that they have permission |
| `SELF_ADD_REACTIONS` | 1 << 21 | Can react to messages, subject to permissions |
| `SELF_DELETE_MESSAGES` | 1 << 22 | Can delete own messages |
| `SELF_EDIT_MESSAGES` | 1 << 23 | Can edit own messages |
| `SELF_EDIT_NAME` | 1 << 24 | Can edit own username, nickname and avatar |
| `SEND_MESSAGES` | 1 << 25 | Can send messages in the channels that they have permissions |
| `USE_ACTIVITIES` | 1 << 26 | Can use voice activities, such as watch together or whiteboard |
| `USE_VIDEO` | 1 << 27 | Can use video and screenshare in guilds/channels that they have permissions |
| `USE_VOICE` | 1 << 28 | Can use voice in guilds/channels that they have permissions |
| `INVITE_USERS` | 1 << 29 | Can create user-specific invites in guilds that they have `INVITE_USERS` |
| `SELF_DELETE_DISABLE` | 1 << 30 | Can delete/disable own account |
| `DEBTABLE` | 1 << 31 | Can use pay-to-use features once paid |
| `CREDITABLE` | 1 << 32 | Can earn money using monetization features in guilds that have `MONETIZATION_ENABLED` |
| `KICK_BAN_MEMBERS` | 1 << 33 | Can kick or ban guild or group DM members in the guilds/groups that they have KICK_MEMBERS, or BAN_MEMBERS |
| `SELF_LEAVE_GROUPS` | 1 << 34 | Can leave the guilds or group DMs that they joined on their own (one can always leave a guild or group DMs they have been force-added) |
| `PRESENCE` | 1 << 35 | Inverts the presence confidentiality default (OPERATOR's presence is not routed by default, others' are) for a given user |
| `SELF_ADD_DISCOVERABLE` | 1 << 36 | Can mark discoverable guilds that they have permissions to mark as discoverable |
| `MANAGE_GUILD_DIRECTORY` | 1 << 37 | Can change anything in the primary guild directory |
| `POGGERS` | 1 << 38 | Can send confetti, screenshake, random user mention (@someone) |
| `USE_ACHIEVEMENTS` | 1 << 39 | Can use achievements and cheers |
| `INITIATE_INTERACTIONS` | 1 << 40 | Can initiate interactions |
| `RESPOND_TO_INTERACTIONS` | 1 << 41 | Can respond to interactions |
| `SEND_BACKDATED_EVENTS` | 1 << 42 | Can send backdated events |
| `USE_MASS_INVITES` | 1 << 43 | Can accept mass (guild) invites |
| `ACCEPT_INVITES` | 1 << 44 | Can accept user-specific invites and DM requests |
| `SELF_EDIT_FLAGS` | 1 << 45 | Can modify own flags |
| `EDIT_FLAGS` | 1 << 46 | Can modify other's flags |
| `MANAGE_GROUPS` | 1 << 47 | Can manage other's groups |
| `VIEW_SERVER_STATS` | 1 << 48 | Can view server stats /api/policies/stats |

10
docs/setup/server/theming/index.md Normal file
View File

@ -0,0 +1,10 @@
# Theming
'Theming' here refers to the theming of the Discord.com web client used for testing.
Fosscord can inject additional CSS into the client to allow you to change quite a lot about it's appearence.
There's three different CSS files injected into the client, in `/assets/public`, including `fosscord-login.css`, `fosscord.css`, and `user.css`.
Fosscord developers may make changes to `fosscord.css` occasionally, so it's best to not touch this.
`user.css` and `fosscord.css` are applied to all routes in the client, while `fosscord-login.css` is only applied to the login/register routes.
You can essentially throw any BetterDiscord/Replugged CSS theme into the `users.css` file and, given it was designed for the same client version, it'll work.

1
mkdocs.yml
View File

@ -31,4 +31,5 @@ markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.superfences