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

Merge pull request #44 from MaddyUnderStars/master

Browse Source 
Update docs for refactor branch
This commit is contained in:
Madeline 2023-01-11 00:26:26 +11:00 committed by GitHub
commit d47fa36f8e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
63 changed files with 1347 additions and 1257 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.prettierrc
View File

@ -1,3 +1,11 @@
{ {
"tabWidth": 4 "trailingComma": "all",
"tabWidth": 4,
"semi": true,
"arrowParens": "always",
"bracketSameLine": false,
"bracketSpacing": true,
"quoteProps": "as-needed",
"useTabs": true,
"singleQuote": false
} }

2
README.md
View File

@ -14,7 +14,7 @@
3. Install dependencies. 3. Install dependencies.
```bash ```bash
python3 -m pip install mkdocs-material mkdocs-render-swagger-plugin mkdocs-section-index python3 -m pip install mkdocs-material mkdocs-swagger-ui-tag mkdocs-section-index
``` ```
4. Edit documents(s). 4. Edit documents(s).

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 `648540060672` 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` | `DEBTABLE` |
| `CREATE_TEMPLATES` | `USE_VOICE` | `PIN_MESSAGES` |
| `CREATE_WEBHOOKS` | `INVITE_USERS` | `SELF_DELETE_DISABLE` |
| `JOIN_GUILDS` | `CREATE_APPLICATIONS` | |
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 |

3
docs/api/routes.md
View File

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

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

11
docs/assets/extra.css Normal file
View File

@ -0,0 +1,11 @@
.md-typeset__table {
min-width: 100%;
}
.md-typeset table:not([class]) {
display: table;
}
.md-grid {
max-width: 65rem;
}

4
docs/assets/favicon.svg Normal file
View File

@ -0,0 +1,4 @@
<svg width="50" height="50" viewBox="0 0 50 50" fill="#ff6e42"
xmlns="http://www.w3.org/2000/svg">
<path d="M 0,0 47.999993,2.7036528e-4 C 48.001796,3.3028172 47.663993,6.5968018 46.991821,9.8301938 43.116101,28.454191 28.452575,43.116441 9.8293509,46.992163 6.5960834,47.664163 3.3023222,48.001868 0,47.999992 Z m 9.8293509,28.735114 v 9.248482 C 22.673599,33.047696 32.857154,22.749268 37.63852,9.829938 H 9.8293509 v 8.679899 H 22.931288 c -3.554489,3.93617 -7.735383,7.257633 -12.373436,9.829938 -0.241031,0.133684 -0.483864,0.265492 -0.7285011,0.395339 z"/>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 571 B

65
docs/assets/js/rightsCalculator.js Normal file
View File

@ -0,0 +1,65 @@
(() => {
const NUM_COLUMNS = 3;
// Grab it from the above markdown table and parse it. Simply don't have multiple tables in the page lol
const rights =
// grab the table data elements
[...document.querySelectorAll("td")]
.map((x) => x.innerText) // get their content
.map((x, i) =>
x.indexOf("<<") == 2 // if this column is the `value` column
? x.split(" ").reverse()[0] // get the value we shift by
: x,
); // otherwise dont do anything
const mount = document.getElementById("rights-container");
const outputMount = document.getElementById("rights-output");
var calculated = 0n;
for (var i = 0; i < rights.length; i += NUM_COLUMNS) {
const name = rights[i];
const shift = rights[i + 1];
const desc = rights[i + 2];
const div = document.createElement("div");
const input = document.createElement("input");
input.setAttribute("type", "checkbox");
input.setAttribute("id", shift);
const label = document.createElement("label");
label.setAttribute("for", label.id);
label.innerText = name.toUpperCase();
div.appendChild(input);
div.appendChild(label);
mount.append(div);
input.addEventListener("click", (event) => {
const value = 1n << BigInt(event.target.getAttribute("id"));
// bit messy, oh well
if (value == 1n) {
if (event.target.checked) {
for (var elem of mount.children) {
elem.children[0].setAttribute("disabled", true);
}
event.target.removeAttribute("disabled");
outputMount.innerText = "1";
return;
} else {
for (var elem of mount.children) {
elem.children[0].removeAttribute("disabled");
}
outputMount.innerText = calculated;
return;
}
}
calculated = event.target.checked
? calculated + value
: calculated - value;
outputMount.innerText = calculated;
});
}
})();

12
docs/assets/logo.svg
View File

@ -1,10 +1,4 @@
<svg width="1148" height="1148" viewBox="0 0 1148 1148" fill="none" xmlns="http://www.w3.org/2000/svg"> <svg width="50" height="50" viewBox="0 0 50 50" fill="white"
<rect width="1148" height="1148" rx="340" fill="url(#paint0_linear_6_79)"/> xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" clip-rule="evenodd" d="M285 283L862 283.003C862.022 322.978 857.961 362.849 849.881 401.987C803.291 627.415 627.023 804.889 403.157 851.801C364.29 859.935 324.697 864.023 285 864V283ZM403.157 630.815V742.76C557.555 683.015 679.971 558.361 737.447 401.983H403.157V507.046H560.653C517.925 554.691 467.668 594.894 411.915 626.03C409.017 627.648 406.097 629.243 403.157 630.815Z" fill="white"/> <path d="M 0,0 47.999993,2.7036528e-4 C 48.001796,3.3028172 47.663993,6.5968018 46.991821,9.8301938 43.116101,28.454191 28.452575,43.116441 9.8293509,46.992163 6.5960834,47.664163 3.3023222,48.001868 0,47.999992 Z m 9.8293509,28.735114 v 9.248482 C 22.673599,33.047696 32.857154,22.749268 37.63852,9.829938 H 9.8293509 v 8.679899 H 22.931288 c -3.554489,3.93617 -7.735383,7.257633 -12.373436,9.829938 -0.241031,0.133684 -0.483864,0.265492 -0.7285011,0.395339 z"/>
<defs>
<linearGradient id="paint0_linear_6_79" x1="574" y1="0" x2="574" y2="1148" gradientUnits="userSpaceOnUse">
<stop stop-color="#FF5F00"/>
<stop offset="1" stop-color="#FF3D00"/>
</linearGradient>
</defs>
</svg> </svg>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 812 B

After

Width:  |  Height:  |  Size: 569 B

3
docs/assets/swagger.css Normal file
View File

@ -0,0 +1,3 @@
html {
overflow-y: auto !important;
}

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_**

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

@ -0,0 +1,51 @@
# 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, helpful, 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 apologizing 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**

79
docs/contributing/index.md
View File

@ -1,63 +1,44 @@
# Contributing # Contributing
By contributing you accept the code of conduct. !!! question "[Have you read the Code of Conduct?](conduct.md)"
## Code of conduct ## Style and a note on etiquette
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. - We use [prettier](https://www.npmjs.com/package/prettier) for code formatting. We have a `.prettierrc` file in fosscord-server's root
and use a git precommit hook to autorun it.
- Try to stay consistent with the rest of the project
- Try to keep each commit to a single feature or idea, with descriptions of what it is and why it is done. No "Large refactor" commits that touch every file,
unless absolutely required due to the nature of change.
- Leave comments in your code about why something is done when appropriate, not just what it is doing.
- If you're working on a feature, please announce that you're working on it (in the relevant GH issue or our Discord, preferably both),
so that we can work more effectively and minimise conflicting change attempts.
Additionally, please do not try to snipe features that others are working on.
Fosscord developer community includes Fosscord Github repositories and Fosscord development guild. ## Structure
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. Fosscord is written in Typescript and is comprised of 4 main parts:
### Desirable behavior - 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.
- 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. ## Implementing endpoints, opcodes, etc
- 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 Generally, the approach is to just see what the Discord.com client sends and receives from Discord.com (through your browsers devtools, for example)
and guessing about any functionality server-side, if it's undocumented.
### Undesirable behavior For a lot of things it's pretty simple to guess, `GET /api/users/@me` returns private details about your user for example.
This route is also detailed in [Discords own documentation](https://discord.com/developers/), [here specifically](https://discord.com/developers/docs/resources/user#get-current-user).
- Talking about things that do not suit the topic of the community. Communities exempt from this rule will mention that in their descriptions. Discord generally does not document anything that is not related to application/bot development, though.
- Attacking people rather than attacking their arguments (a.k.a. ad hominem). As an example, `GET /api/updates?platform={}` which returns the `url`, `pub_date`, `name` and any `notes` about the latest client release for a platform.
- 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 For the Gateway it's the same procedure, except now you can't use the network logger of your devtools
because the gateway returns responses encoded with [erlpack](https://github.com/discord/erlpack).
Easy fix though, just edit the `DeveloperOptionsStore` localStorage key so that `logGatewayEvents` is true, and reload the client.
- 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. !!! warning
- 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 Make sure you rerun `npm run build` every time you edit source code. Additionally, make sure you run `npm run generate:schema` whenever you change a
schema. If you want to do both, there's a shortcut: `npm run setup`.
- 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

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";
```

108
docs/faq.md
View File

@ -1,26 +1,100 @@
# Frequently Asked Questions # Frequently Asked Questions
## Can I get free Nitro? ??? info "Voice/Video when?"
We Fosscord developers and server administrators can't grant you free nitro at discord.com. Currently there is no voice or video support in any Fosscord instance.
A Fosscord instance administrator may choose to grant you free nitro or its equivalent powers in its own instance. This is a very difficult feature to get working, especially given that
Do not beg for free Nitro in Fosscord Github repository, or in Fosscord Official Development Guild. we must implement it the exact same way as Discord.com for client compatibility.
[We would be incredibly thankful for any assistance.](/contributing)
## Why are we reimplementing and extending the Discord protocol? ??? info "Free Nitro?"
1. Despite its API complexity, underlying working principle of the protocol is quite simple. No complex conflict resolution like, say, Matrix. Please do not use Discord trademarks to refer to anything regarding Fosscord.
2. People want persistent decentralised chats. Also to speak, Discord's event ordering is strictly linear, which again simplifies server, client and bot development. As an instance owner, you can grant yourself or others *premium* features which may be used to determine your abilities
3. Discord protocol has event authorisation finality, which simplifies the server design. *client-side*. However, Fosscord-server currently does not have any distinction between premium and free users.
4. The server does most of the heavy lifting, which allows for more easy client and bot development. All users can access all features, given they have the [rights](setup/server/security/rights.md) to do so.
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? You cannot give yourself premium features on Discord.com using a Fosscord instance.
As always, we don't give ETAs; because users tend to reinterpret ETAs as committed due dates. ??? info "How do I boost my guild? Or, how do I buy premium?"
## When is the next stable version going to be released? You cannot buy premium features through Fosscord, as Fosscord does not support any payment backend.
When it's ready. Additionally, Fosscord does not currently have any distinction between premium and free users or guilds.
All users and guilds have access to all features server-side.
In the case of users, you may run into issues with the client preventing you from using certain features,
if the user's `premium_type` or `premium` values are not set correctly. By default, Fosscord will do this for you, however.
In the case of guilds, you may run into issues with uploading animated icons or banners, etc.
If so, simply give the guild the [features](setup/server/configuration/guildFeatures.md) you require.
You can set them to be given to all guilds by default using the [config](setup/server/configuration/index.md) `guild_defaultFeatures` array.
??? info "Can I log in with my Discord account?"
No. Fosscord and Discord are entirely separate services, with their own separate databases
and authentication. Fosscord cannot access any private data from Discord.com.
As always, you should not provide login credentials for Discord.com, or any other service,
to others.
??? info "Does Fosscord use the same servers as Discord?"
No. Discord servers, as in the bare-metal running the service, are completely inaccessible
to people, outside of course the Discord.com service provided. It is impossible for us to use their
infrastructure. Fosscord instances are hosted entirely by their owner(s).
If you mean Discord 'server' as in a *guild*, also no. Fosscord is not a proxy for
Discord guilds. Fosscord does not create Discord.com accounts or ask for your own at any time
(outside of OAuth features provided by the instance such as account connections or 'login with' buttons)
If Fosscord was to try this, Discord's automated spam filters would surely block your instance,
and ban any offending accounts.
Lastly, you can simply view [our codebase](https://github.com/fosscord/fosscord-server).
A simple proxy would not need to be this complex or large.
We implement the entire Discord.com API, Gateway, among others.
None of this would be necessary if we were simply abusing Discord.com.
??? info "Do you use Discord.com code?"
Absolutely not. If a potential contributor makes any indication of being a Discord employee,
or to have access to leaked Discord.com code, we take measures in line with our [Code of Conduct](/contributing/conduct.md)
to ensure the Fosscord codebase is free of any proprietary code. We want absolutely nothing to do with it.
??? info "What about the test client? That's just the Discord.com one!"
Yes, this is true. However, this is purely for testing and development purposes.
Fosscord is first and foremost a *backend* server implementation, and we simply use Discord.com's client
to verify our work as correct. Efforts are being made to move away from this with our own client, but as you may have guessed,
building a Discord-compatible client is difficult.
You can read more about the test client [here](setup/server/Test%20Client/index.md)
??? info "Is this illegal?"
The Fosscord maintainers do not believe it to be, no. See: [Oracle v. Google](https://en.wikipedia.org/wiki/Google_LLC_v._Oracle_America,_Inc.).
The only aspect of Fosscord that is not entirely written by us is the test client which we simply proxy from Discord.com,
and we take measures to show that the client is purely for development and research purposes.
??? info "Why are you doing this, anyway?"
1. We love free, open source software.
2. There are many existing bots, applications, users, features, and ideas surrounding Discord.com.
3. Fosscord allows these users and developers to maintain a familiar ecosystem with minimal friction.
4. Reimplementing allows us to extend the Discord protocol in ways Discord.com may not deem feasible, economical, whateverical.
5. This includes privacy features, such as end to end encryption for example.
6. The reverse engineering effort by our team may be useful to outside developers looking to understand how similar services work.
7. The Discord protocol, despite its API complexity, is quite simple and linear. No complex conflict resolution like Matrix, for example.
??? info "Editing the database is annoying, is there a graphical interface for this?"
Currently no, there is no graphical interface for managing your Fosscord instance.
An admin dashboard is planned, but we currently have higher priorities right now.
??? info "When will this feature be available?"
We do not provide ETAs. Users tend to take them as deadlines, and for a small team of <5 maintainers
who do not get payment for their work, this is unreasonable.
??? info "It's pretty funny how you have a Discord.com guild for support."
We know. Also that's not a question.

62
docs/index.md
View File

@ -1,53 +1,35 @@
# Home # Home
Just wanna get to setup instructions? Click [here](server/setup.md)! !!! note "Interested in contributing? We'd love to have you on board! [Click here](contributing)"
### What is Fosscord? !!! tip "Want to skip to the server installation guide? [Click here](setup/server)"
Fosscord is a free open source self-hostable discord compatible chat, voice and video platform. !!! question "Have a question? It might be in [here](faq.md)"
## Philosophy ## What is Fosscord?
Fosscord aims to be a full one-on-one clone of Discord, adding more features Fosscord is a Discord.com server implementation and extension,
that can be used as a replacement for the official client and still connect to with the goal of complete feature parity with Discord.com,
discord.com and host private Fosscord server instances. all while adding some additional goodies, security, privacy, and configuration options.
Fosscord aims to give the best possible user experience, while being backwards Fosscord allows you to host a complete, Discord.com-compatible chat service
compatible to Discord's features and adding new ones/improving old ones while with complete control over it's content, usage, security, configuration, and featureset.
maintaining the user privacy with end-to-end encryption support. Being Discord.com-compatible will allow all existing clients, bots, and applications written for
Discord.com to be used on any Fosscord instance, which we believe will be immensely useful
for any transition process between services.
The client can connect to multiple server instances without the need to open it As Fosscord is an entirely separate service from Discord.com, it means a Fosscord server by itself **cannot**
multiple times. 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 should be extensible through a secure Plugin and Theme System with Our goal is to achieve complete feature parity with Discord.com, as well as
own store. 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
The server should be extensible through bots, just like discord without the need to multiple Fosscord-compatible instances with rich theming and plugin support.
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 ## Support
[Discord server](https://discord.gg/ZrnGQP6p3d) For any kind of support regarding Fosscord, feel free to ask questions in our [Discord.com server](https://discord.gg/Ms5Ev7S6bF)
or our [official Fosscord instance](https://staging.fosscord.com).
Once we are finished, we'll host our own instance to host the support server. For bug reporting and feature requests please create an [issue](https://github.com/fosscord/fosscord-server/issues/new/choose) on Github.

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

10
docs/routes.md Normal file
View File

@ -0,0 +1,10 @@
# API Routes
<style>
#api-routes, .md-sidebar--secondary {
display: none !important;
}
</style>
<swagger-ui src="https://raw.githubusercontent.com/fosscord/fosscord-server/maddy/refactor/assets/openapi.json"/>
<!-- <swagger-ui src="/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 |

40
docs/server/env.md
View File

@ -1,40 +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 the fosscord-server directory. 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.
!!! WARNING "Multithreading is currently broken, so you should define THREADS=1"
## 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)

65
docs/server/setup.md
View File

@ -1,65 +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) v16+
- [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 and is a correct version by just running `python -V`"
#### Setup
Open a shell/terminal and execute these commands:
```
git clone https://github.com/fosscord/fosscord-server
cd fosscord-server
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 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 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");
}
```

67
docs/setup/clients/index.md Normal file
View File

@ -0,0 +1,67 @@
## Using your Discord.com desktop client with a Fosscord instance
=== "Environment Variables"
This assumes your Fosscord instance has the [Test Client](../server/Test%20Client/) enabled, and [erlpack](https://npmjs.com/package/@yukikaze-bot/erlpack) installed.
Set the `DISCORD_WEBAPP_ENDPOINT` environment variable on the machine running the client to the Fosscord web app URL, for example `https://staging.fosscord.com`.
On Windows:
1. Open the start menu and search for "Environment variables"
2. Click "Environment Variables" at the bottom of this new window, titled "System Properties"
3. Add a new user variable
4. Set the name to `DISCORD_WEBAPP_ENDPOINT`, and the value to your instance URL.
On Linux, you can:
* run `DISCORD_WEBAPP_ENDPOINT=instance url discord` on the CLI
* edit the `discord.desktop` file to include the above
* add `EXPORT DISCORD_WEBAPP_ENDPOINT=url` to your bash/zsh/etc profile (`~/.bashrc` for example)
* and probably lots more
=== "settings.json"
This assumes your Fosscord instance has the [Test Client](../server/Test%20Client/) enabled, and [erlpack](https://npmjs.com/package/@yukikaze-bot/erlpack) installed.
You may edit your desktop client's `settings.json` file at
`%appdata%/discord/settings.json` on Windows and typically
`~/.config/discord/settings.json` on Linux,
adding the following line
```json
"WEBAPP_ENDPOINT" : "https://your_fosscord_instance_url"
```
such that it looks like this, as an example
```json
{
"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"
}
```
=== "Webcord"
This assumes your Fosscord instance has the [Test Client](../server/Test%20Client/) enabled.
Webcord does not currently allow specifcying custom instance URLs.
The available instances with Webcord are [https://app.freecord.ir](Freecord) and
[staging.fosscord.com](https://staging.fosscord.com).
1. Download and install [Webcord](https://github.com/SpacingBat3/WebCord)
2. In the top bar, "File" -> "Settings"
3. Scroll down to "Discord Instance" and select a Fosscord instance you would like to use
=== "Host the proxy yourself"
If an instance does not have the test client enabled, you can [host the proxy yourself](https://github.com/fosscord/Discord-Client-Proxy), and simply set it to use your desired Fosscord instance.

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

@ -0,0 +1,5 @@
## [Server](server)
## [Bots](bots)
## [Clients](clients)

20
docs/setup/server/Test Client/index.md Normal file
View File

@ -0,0 +1,20 @@
# Test Client
!!! warning "The test client included with fosscord-server is deprecated and will be removed in favour of [Dicord-Client-Proxy](http://github.com/fosscord/Discord-Client-Proxy) in the future"
The test client is a proxy to the Discord.com client used for development purposes.
You can enable the test client by setting the `client_useTestClient` [config](../configuration/index.md) value.
By editing the `GLOBAL_ENV` variable used by the client, we can trick it into sending requests to the API/Gateway/CDN/etc to us,
instead of Discord.com.
## Updating
To update the client version served, edit the 4 `<script>` tags in the `<body>` of `assets/client_test/index.html`,
with ones used by a client version you wish to use.
To get the latest client scripts, simply download the HTML served by [https://discord.com/app](https://discord.com/app) (through `wget https://discord.com/app`, for example)
Do not replace the `assets/client_test/index.html` file with a fresh one from Discord.com, as there are additional changes made to the file by the Fosscord team.
## [Theming](theming.md)
## [Plugins](plugins.md)

17
docs/setup/server/Test Client/plugins.md Normal file
View File

@ -0,0 +1,17 @@
There is no plugin API available to use with the test client currently.
You cannot install BetterDiscord, Powercord/Replugged, or other client mod plugins without heavy modification at this time.
However, you _can_ install [Vencord](https://github.com/Vendicated/Vencord)
quite easily with only slight modifications to the [user script](https://github.com/Vendicated/Vencord#installing-on-browser).
For instances you control, simply find and replace all mentions of `GM_xmlhttpRequest` with `new XMLHttpRequest`, and `unsafeWindow` with `window`.
Throw the edited file into the `assets/preload-plugins` directory, restart the server, and you now have Vencord installed instance-wide!
If you want to install Vencord on instances you do not control, do not perform any of the above steps, and simply modify
the `@match` line at the top to include the instance(s). For [staging.fosscord.com](https://staging.fosscord.com):
```js
// @match *://*.staging.fosscord.com/*
```
You may now install the modified user script in your favourite user script browser extension, such as [Tampermonkey](https://www.tampermonkey.net/)

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

@ -0,0 +1,10 @@
# Theming
'Theming' here refers to the theming of the [test client](index.md).
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.

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

@ -0,0 +1,19 @@
# Embeds
Embeds in Fosscord are external content that is displayed within your messages when linked to.
Fosscord tries its best to fetch content from these external sites,
but sometimes we require an API key or other authentication with the site to display their content (or nicer looking embeds).
For external images, it's best to set up [Imagor](imagor.md) for image resizing.
The client may or may not fetch images directly from their source if this is not set up,
and as such some users may not see all images.
In the case where a client does fetch an image from it's source, without Imagor an attacker
may be able to learn the IP addresses of users.
## Twitter
Go to the [Twitter developer portal](https://developer.twitter.com/) and sign up for developer access.
You must have a phone number attached to your account to sign up.
Create an application for use with the Twitter API (We don't need to post messages to Twitter itself).
Make sure to create a bearer token for authentication.
Once you have your API key, set the `external_twitter` [config](index.md) value to your API key, wrapped in quotes.

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

@ -0,0 +1,20 @@
# 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 except messages from gateway |
| WS_VERBOSE | boolean | If set, log websocket messages received by 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 are 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 guild features is available [here](https://github.com/Delitefully/DiscordLists#guild-feature-glossary)

66
docs/setup/server/configuration/imagor.md Normal file
View File

@ -0,0 +1,66 @@
# 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. Downloading images directly from the host may lead to
privacy concerns, as an attacker may be able to learn users IP addresses.
## 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 (do not include the `[]`)
```
IMAGOR_SECRET=[security_requestSignature value]
PORT=8000
```
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 would like to change the port Imagor listens on, be sure to change both the PORT value in `imagor.env`,
and the `-p` value used in docker.
If you're using a [reverse proxy](../reverseProxy.md) such as Nginx for Fosscord already, you could add this to your config's `server` block
```nginx
location /media {
# If you changed the port, be sure to change it here too
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.
??? "Example config for `media.whatever.com` site"
```nginx
server {
# Change the server_name to reflect your true domain
server_name media.whatever.com
add_header Last-Modified $date_gmt;
proxy_set_header Host $host;
proxy_pass_request_headers on;
proxy_set_header X-Forwarded-For $remote_addr;
location / {
# If you had changed the port, change it here as well
proxy_pass http://127.0.0.1:8000;
}
}
```
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!

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

@ -0,0 +1,144 @@
# 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/).
!!! note "The `CONFIG_PATH` [environment variable](env.md) can be set to make Fosscord use a JSON file instead of a database table."
## Array Types
Arrays are represented by \_[number] in a config key. For example, multiple `guild_defaultFeatures` may be assigned such as
| key | value |
| ------------------------- | --------------- |
| `guild_defaultFeatures_0` | `DISCOVERABLE` |
| `guild_defaultFeatures_1` | `ANIMATED_ICON` |
| etc | etc |
## Available Configuration Options
| key | default | type | description |
| -------------------------------------------------- | -------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------- |
| gateway_endpointClient | null | string | Injected into index.html if available |
| gateway_endpointPrivate | null | string | Used for internal communication with gateway |
| gateway_endpointPublic | null | string | Publicly announced gateway endpoint |
| cdn_endpointClient | null | string | See gateway_endpointClient |
| cdn_endpointPrivate | http://localhost:3001 | string | See gateway_endpointPrivate |
| cdn_endpointPublic | http://localhost:3001 | string | See gateway_endpointPublic |
| cdn_resizeHeightMax | 1000 | number | Maximum image resize height for embeds. |
| cdn_resizeWidthMax | 1000 | number | Maximum image resize width for embeds. |
| [cdn_imagorServerUrl](imagor.md) | null | string | Imagor instance endpoint for external image resizing. |
| api_defaultVersion | 9 | string | API version to use when not specified |
| api_activeVersions_0 | 6, 7, 8, 9 | string[] | Allowed API version numbers. [Array](#array-types). |
| general_instanceName | Fosscord Instance | string | Announced instance name |
| general_instanceDescription | This is a Fosscord instance made in the pre-release days | string | Announced instance description |
| general_frontPage | null | string | Announced instance front page |
| general_tosPage | null | string | Announced instance TOS page |
| general_correspondenceEmail | null | string | Announced instance correspondence email |
| general_correspondenceUserID | null | string | Announced instance correspondence ID (from this instance) |
| general_image | null | string | Announced instance image URL |
| general_instanceId | Snowflake of instance creation date | Snowflake | Announced instance ID |
| limits_user_maxGuilds | 1048576 | number | Maxmimum guilds a user can join |
| limits_user_maxUsername | 127 | number | Maximum username length |
| limits_user_maxFriends | 5000 | number | Maximum number of friends per user |
| limits_guild_maxRoles | 1000 | number | Maximum number of roles in a guild |
| limits_guild_maxEmojis | 2000 | number | Maximum number of emojis in a guild |
| limits_guild_maxMembers | 25000000 | number | Maximum number of members in a guild |
| limits_guild_maxChannels | 65535 | number | Maximum number of channels in a guild |
| limits_guild_maxChannelsInCategory | 65535 | number | Maximum number of channels per category in a guild |
| limits_message_maxCharacters | 1048576 | number | Maximum character count per message |
| limits_message_maxTTSCharacters | 160 | number | Maximum character count per text to speech messages |
| limits_message_maxReactions | 2048 | number | Maximum number of reactions per message |
| limits_message_maxAttachmentSize | 1073741824 | number | Maximum total attachment size per message |
| limits_message_maxBulkDelete | 1000 | number | Maximum number of messages deletable through bulk delete |
| limits_message_maxEmbedDownloadSize | 5242880 | number | Maximum download size of external embeddable content |
| limits_channel_maxPins | 500 | number | Maximum number of pins per channel |
| limits_channel_maxTopic | 1024 | number | Maximum channel topic character length |
| limits_channel_maxWebhooks | 100 | number | Maximum number of webhooks per channel |
| limits_rate_enabled | true | boolean | Whether rate limits are enabled |
| limits_rate_ip_count | 500 | number | Allowed number of requests per IP within window |
| limits_rate_ip_window | 5 | number | IP rate limit window, in seconds |
| limits_rate_global_count | 250 | number | Allowed number of requests globally within window |
| limits_rate_global_window | 5 | number | Global rate limit window, in seconds |
| limits_rate_error_count | 10 | number | Number of allowed errors per user within window |
| limits_rate_error_window | 5 | number | User error rate limit window, in seconds |
| limits_rate_routes_guild_count | 5 | number | Allowed number of /guild\* requests per user within window |
| limits_rate_routes_guild_window | 5 | number | User /guild\* rate limit window, in seconds |
| limits_rate_routes_webhook_count | 10 | number | Allowed number of /webhooks\* requests per user within window |
| limits_rate_routes_webhook_window | 5 | number | User /webhooks\* rate limit window, in seconds |
| limits_rate_routes_channel_count | 10 | number | Allowed number of /channel\* requests per user within window |
| limits_rate_routes_channel_window | 5 | number | User /channel\* rate limit window, in seconds |
| limits_rate_routes_auth_login_count | 5 | number | Allowed number of IP /login requests within window |
| limits_rate_routes_auth_login_window | 60 | number | IP /login rate limit window, in seconds |
| limits_rate_routes_auth_register_count | 2 | number | Allowed number of IP /register requests within window |
| limits_rate_routes_auth_register_window | 43200 | number | IP /register rate limit window, in seconds |
| limits_absoluteRate_register_limit | 25 | number | Absolute number of registrations instance-wide per window |
| limits_absoluteRate_register_window | 3600000 | number | Global /register rate limit window, in seconds |
| limits_absoluteRate_register_enabled | true | boolean | Whether absolute register rate limits are enabled |
| limits_absoluteRate_sendMessage_limit | 200 | number | Absolute number of messages instance-wide per window |
| limits_absoluteRate_sendMessage_window | 60000 | number | Global sendMessage window, in seconds |
| limits_absoluteRate_sendMessage_enabled | true | boolean | Whether absolute message sending rate limits are enabled |
| [security_captcha_enabled](../security/captcha.md) | false | boolean | Whether to enable captchas for login/register |
| security_captcha_service | null | "recaptcha"/"hcaptcha" | Which captcha service to use |
| security_captcha_sitekey | null | string | Captcha service sitekey |
| security_captcha_secret | null | string | Captcha service secret |
| security_twoFactor_generateBackupCodes | true | boolean | Whether to generate backup codes for MFA users |
| security_requestSignature | Secret secret | string | The signature required for CDN or [Imagor](imagor.md) usage |
| security_jwtSecret | Secure secret | string | The secret used for user token generation |
| [security_forwadedFor](../reverseProxy.md) | null | string | HTTP header for user's real IP. |
| security_ipdataApiKey | Fosscord IPdata key | string | API key used for IP geolocation and proxy detection |
| security_mfaBackupCodeCount | 10 | number | Number of MFA backup codes to generate |
| security_statsWorldReadable | true | boolean | Whether instance stats are publically accessible or require right |
| security_defaultRegistrationTokenExpiration | 604800000 | number | Seconds for [registration tokens](../security/regTokens.md) to expire |
| login_requireCaptcha | false | boolean | Whether login requires captcha verification |
| register_email_required | false | boolean | Whether an email is required for registration |
| register_email_allowlist | false | boolean | Whether `register_email_domains` is an allowlist |
| register_email_blocklist | true | boolean | Whether `register_email_domains` is a blocklist |
| register_email_domains | [] | string[] | The email domains list to use as a block/allow list |
| register_dateOfBirth_required | true | boolean | Whether a date of birth is required for registration |
| register_dateOfBirth_minimum | 13 | number | The minimum age of registration |
| register_password_required | false | boolean | Whether a password is required for registration |
| register_password_minLength | 8 | number | Minimum password length |
| register_password_minNumbers | 2 | number | Minimum number of number characters in passwords |
| register_password_minUpperCase | 2 | number | Minimum number of uppercase characters in passwords |
| register_password_minSymbols | 0 | number | Minimum number of symbols in passwords |
| register_disabled | false | boolean | Whether registration is disabled |
| register_requireCaptcha | true | boolean | Whether registration requires captcha verification |
| register_requireInvite | false | boolean | Whether registration requires a guild invite |
| register_guestsRequireInvite | true | boolean | Whether guests accounts require a guild invite |
| register_allowMultipleAccounts | true | boolean | Allow multiple accounts with the same client fingerprint |
| register_blockProxies | true | boolean | Whether proxies are blocked from registration |
| register_incrementingDiscriminators | false | boolean | Whether discriminators are random or incrementing |
| [register_defaultRights](../security/rights.md) | 30644591655940 | string | The rights assigned to users _upon registration_ |
| regions_default | fosscord | string | The default voice region to use |
| regions_useDefaultAsOptimal | true | boolean | Whether to calculate closest or use default as optimal voice region |
| regions_available_0_id | fosscord | string[] | The available voice region IDs |
| regions_available_0_name | Fosscord | string[] | The available voice region names |
| regions_available_0_endpoint | 127.0.0.1:3004 | string[] | The available voice region endpoint URLs |
| regions_available_0_vip | false | boolean[] | Whether this voice region is VIP exclusive |
| regions_available_0_custom | false | boolean[] | Whether this is a custom voice region (used for events/etc) |
| regions_available_0_deprecated | false | boolean[] | Whether this is a deprecated voice region (clients avoid these) |
| guild_discovery_showAllGuilds | false | boolean | Whether guild discovery should show all guilds |
| guild_discovery_limit | 24 | number | Maximum number of guild discovery elements per page |
| guild_autoJoin_enabled | true | boolean | Whether users auto join guild(s) on registration |
| guild_autoJoin_canLeave | true | boolean | Whether users can leave the auto-joined guild(s) |
| [guild_defaultFeatures_0](guildFeatures.md) | null | string | Features automatically granted to guilds upon creation |
| gif_enabled | true | boolean | Whether GIF features are enabled |
| gif_provider | tenor | "tenor" | Which GIF service to use |
| gif_apiKey | LIVDSRZULELA | string | GIF service API key |
| [rabbitmq_host](rabbitmq.md) | null | string | RabbitMQ connection string |
| templates_enabled | true | boolean | Whether guild templates are enabled |
| templates_allowTemplateCreation | true | boolean | Whether new guild templates can be created |
| templates_allowDiscordTemplates | true | boolean | Whether guild templates from Discord.com can be fetched |
| [templates_allowRaws](/concepts/guildTemplates.md) | true | boolean | Whether raw guild templates are allowed |
| client_useTestClient | false | boolean | Whether the Discord.com test client is enabled |
| sentry_enabled | false | boolean | Whether server-side Sentry analytics is enabled |
| sentry_endpoint | Fosscord sentry endpoint | string | Sentry endpoint |
| sentry_traceSampleRate | 1 | number | Sentry sample rate (1 means all requests) |
| sentry_environment | System hostname | string | Sentry environment name |
| defaults_user_premium | false | boolean | Whether users are given premium upon registration |
| defaults_user_premium_type | 2 | number | The premium type given to users upon registration |
| defaults_user_verified | true | boolean | Whether users get verified email upon registration |
| [external_twitter](embeds.md) | null | string | Twitter API key used for Twitter embeds |

14
docs/setup/server/configuration/rabbitmq.md Normal file
View File

@ -0,0 +1,14 @@
# RabbitMQ
[RabbitMQ](https://www.rabbitmq.com/) is an open source message broker.
Fosscord can be configured to use it for communication between the API server and Gateway server.
RabbitMQ is required to be set up when you run the API and Gateway servers separately (outside of bundle).
Without it, the Gateway server won't know when you send new events for things such as message creation.
In the message create case, you will be able to send messages, but will have to reload the client to view new messages from others.
After you've downloaded and installed RabbitMQ,
edit Fosscord's [config](index.md), set `rabbitmq_host` to `"amqp://guest:guest@host:5672"`
The `guest` RabbitMQ account can only be accessed via localhost, by default.
If you want to run Fosscord over multiple systems,
you'll need to set up [access control](https://www.rabbitmq.com/access-control.html) in RabbitMQ.

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 shiny new 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`

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

@ -0,0 +1,56 @@
# 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 or Heroku.
You **must** have access to a terminal for this guide.
We do not recommend using Windows to run Fosscord.
## 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.
(See: `python-is-python3` package)
- 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 `Desktop development with C++` package.
You do not need the full Visual Studio install, the build tools are fine.
## 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
# 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!
If you set up your server remotely, you can use `curl http://localhost:3001/api/ping` to verify the server is up and running,
(you should set up a reverse proxy, next!).
## 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)

20
docs/setup/server/migatingFromStaging.md Normal file
View File

@ -0,0 +1,20 @@
# Migrating from Staging
'Staging' refers to [this branch](https://github.com/fosscord/fosscord-server/tree/staging) of fosscord-server,
which is deprecated in favour of [the refactor branch](https://github.com/fosscord/fosscord-server/tree/maddy/refactor) (if this is a 404, its just become the main branch now).
!!! warn "If you were using SQLite, you will be unable to migrate to the new version. SQLite is primarily for testing and development purposes, and it should not be used for production."
To migrate from Staging:
1. Download the new version of fosscord-server
`git clone https://github.com/fosscord/fosscord-server.git`
2. Copy your `.env` file from your previous installation to the new `fosscord-server` folder.
3. Copy any user data, specifically the `files` directory, to the new project root.
4. `npm i` in new installation
5. `npm run setup`
6. `npm run migrate-from-staging` to run the migrations on your database
7. `npm run start` to start the server
Make sure you modify any existing scripts of yours to use the new path,
or just rename the old one and move the new one in its place.

60
docs/setup/server/npmScripts.md Normal file
View File

@ -0,0 +1,60 @@
# NPM scripts
Can be executed using `npm run {script name}`
## `setup`
Shorthand for `build` and `generate:schema`
## `sync:db`
Syncronise the database schema between Fosscord source code and your database.
**May incur data loss**. You do not normally need to run this script, as Fosscord-server will perform it when necessary.
## `build`
Builds the Fosscord source code
## `start`
Starts the bundled server. API, Gateway, and CDN run under the same process when using bundle, using the same port.
## `start:api`, `start:gateway`, `start:cdn`
Starts the respective component.
## `generate:client`
Downloads a (mostly) complete discord.com web client and runs some basic patches:
- Replaces all mentions of "Server" -> "Guild"
- Replaces "Discord" -> "Fosscord"
- "Nitro" -> "Premium"
- Replaces the Discord logo home button with a Fosscord logo
- Prevents `localStorage` deletion (for [plugins](Test%20Client/plugins.md))
- Adds `fast-identify` support
The script can only search for all javascript client files,
as it is difficult to determine the filetype of other assets.
Instead, it uses a `cacheMisses` file in `fosscord-server/assets`
generated at server runtime.
### fast-identify
Essentially, it's a small mod to the fast-connect script Discord clients already use,
which sends a small `IDENTIFY` payload to the server, which speeds up how fast we receive `READY`.
Without the client patch however, the `READY` payload received will just be ignored by the client,
and it'll attempt to re-auth after a few seconds.
## `generate:rights`
Generates a Discord.com-like rights value for use as a default right.
Also displays the 'all rights' value, which `1` is a placeholder for.
## `generate:changelog`
Injects the changelog at `fosscord-server/assets/changelog.txt` into the Discord.com client.
## `generate:schema`
Recreates the `fosscord-server/assets/schema.json` file, which is used for API and Gateway request validation.

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

@ -0,0 +1,78 @@
# 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`
!!! info
Other distros, and Windows, may not have a `sites-available`, `sites-enabled` directory structure.
You may need to edit the `/etc/nginx/nginx.conf` file instead, or place new files in a `conf.d` directory, for example.
Check which directories exist on your system to be sure.
```nginx
server {
# Change server_name
server_name fosscord.example.com;
listen 80;
location / {
# Only change this if Nginx and Fosscord are not on the same machine.
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";
}
# Uncomment this if using Imagor:
#location /media {
# # If you changed the port, be sure to change it here too
# proxy_pass http://127.0.0.1:8000;
#}
}
}
```
## SSL
[SSL](https://en.wikipedia.org/wiki/Secure_Sockets_Layer) is a technology used to keep your website secure.
Put very simply, it's the padlock next to the URL in your browser.
After you've set up NGINX, it's very simple to also set up SSL using `certbot`.
=== "Ubuntu"
```sh
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx
```
=== "Arch"
```sh
sudo pacman -Syu certbot certbot-nginx
sudo certbot --nginx
```
=== "Other Distros"
Please refer to [Certbots documentation](https://certbot.eff.org/)
You should be asked various questions, such as which site you want to enable SSL for.
After which, you should now have a SSL secured Fosscord instance!
But wait, there's more! 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`).

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

@ -0,0 +1,25 @@
# CAPTCHAs
Fosscord currently supports two CAPTCHA providers; reCAPTCHA and hCaptcha.
=== "hCaptcha"
1. Navigate to [https://www.hcaptcha.com/](https://www.hcaptcha.com/)
2. Create an account - `Add hCaptcha for Publishers to my website or app`
3. Copy your `sitekey` to the [config](../configuration/index.md) `security_captcha_sitekey` value, wrapped in quotes
4. Copy your `secret` to the config `security_captcha_secret` value, wrapped in quotes
5. Set the config `security_captcha_service` value to `"hcaptcha"`
6. Set the `security_captcha_enabled` value to `true`, *not* wrapped in quotes.
=== "reCAPTCHA"
1. Navigate to [https://www.google.com/u/1/recaptcha/admin/create](https://www.google.com/u/1/recaptcha/admin/create)
2. Fill in your websites details
3. Select `reCAPTCHA v2` -> `"I'm not a robot" Checkbox`
4. Add your domain. For example, `staging.fosscord.com`. Go to the next screen.
5. Copy your `sitekey` to the [config](../configuration/index.md) `security_captcha_sitekey` value, wrapped in quotes
6. Copy your `secret` to the config `security_captcha_secret` value, wrapped in quotes
7. Set the config `security_captcha_service` value to `"recaptcha"`
8. Set the `security_captcha_enabled` value to `true`, *not* wrapped in quotes.
reCAPTCHA v3 and other v2 types may or may not work.

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)

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

@ -0,0 +1,44 @@
# Rate Limiting
Fosscord has various forms of rate limiting built in. If you are logged in, you can bypass these with the `BYPASS_RATE_LIMITS` [right](rights.md)
- Absolute rate limits, which effect all requests to a route regardless of source (`limits_absoluteRate_*`)
- User or IP specific rate limits (`limits_rate_*`)
## Absolute ratelimiting
There are currently two types of absolute rate limiting:
- `limits_absoluteRate_register_*` - Controls the absolute count of registrations allowed within a window. Useful for mitigating registration spam, in addition to [captchas](captcha.md)
- `limits_absoluteRate_sendMessage_*` - Controls the absolute count of messages allowed to be sent within a window.
Absolute rate limits do not consider the source of the request, only the total number of requests instance-wide.
Both of the above are individually enabled.
## User/IP specific ratelimiting
These rate limits are enabled with a single toggle (`limits_rate_enabled`)
- `limits_rate_ip_*` - Controls the count of requests to any endpoint from a single IP over some window.
- `limits_rate_global_*` - Number of requests to any endpoint for the same user and IP
- `limits_rate_error_*` - Number of errors allowed per window for an IP
- `limits_rate_routes_guild_*` - Guild related requests for same user and IP
- `limits_rate_routes_webhook_*` - Webhook related requests for same user and IP
- `limits_rate_routes_channel_*` - Channel related requests for same user and IP
- `limits_rate_routes_auth_login_*` - Login requests for same user and IP
- `limits_rate_routes_auth_register_*` - Register requests (successful only) for same IP
## What do you mean by window and count?
Each ratelimiter accepts a `window` and `count`. The rate limiter tracks the number of requests to an endpoint within a `window`, in seconds.
If number of requests within the last `window` seconds exceeds the `count` set, it will block the request.
For example, setting:
```
limits_rate_ip_count = 10
limits_rate_ip_window = 1
```
will prevent all requests to any API endpoints from an IP if they exceed 10 requests in 1 second.

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

@ -0,0 +1,29 @@
# Registration Tokens
Registration tokens are a one-time use token for allowing a new user registration to bypass various restrictions:
- Bypass `register_allowNewRegistrations = false`
- Bypass `register_disabled = true`
- Bypass [captchas](captcha.md)
- Bypass `register_allowMultipleAccounts = false`
- Bypass `register_blockProxies = true`
- Bypass `register_requireInvite = true`
- Bypass `register_guestsRequireInvite = true`
- Bypass [absolute register rate limits](limits.md)
To create a registration token, send a GET request to `/auth/generate-registration-tokens` as an account with `OPERATOR` [rights](rights.md).
There are a few query parameters available. Append them to the request URL, for example `/auth/generate-registration-tokens?count=10&plain=true`
| Parameter | Type | Default | Description |
| ------------- | ---- | ------- | ------------------------------------------------- |
| `count` | int | 1 | The number of tokens to generate |
| `plain` | bool | false | Return a newline separated string instead of JSON |
| `length` | int | 255 | The length of each returned token |
| `include_url` | bool | false | Prefix tokens with URL to register page |
To use a registration token, append `?token={your registration token}` to the register route. For example
```
https://staging.fosscord.com/register?token=some token
```

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

@ -0,0 +1,116 @@
## About
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. The script generates a rights value that mimicks Discord.com.
## OPERATOR Rights
!!! danger "It is EXTREMELY DISCOURAGED to give OPERATOR rights to all users, or to set the default rights to OPERATOR. If your rights value is an odd number, that includes operator."
Operator rights currently grants access to the following, in addition to all rights:
- Server shutdown through GET `/api/stop`
- [Registration token creation](regTokens.md) through GET `/api/auth/generate-registration-tokens`
## Calculator
<style>
#rights-calculator * {
padding: 0;
margin: 0;
font-size: 0.65rem;
}
#rights-calculator #rights-container {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
}
#rights-calculator #rights-container input {
margin-right: 10px;
width: 20px;
height: 20px;
}
#rights-calculator #rights-output-container {
margin-top: 10px;
padding: 10px;
background-color: rgba(0, 0, 0, 0.3);
border-radius: 10px;
}
</style>
<div id="rights-calculator">
<div id="rights-container"></div>
<div id="rights-output-container">
<p>Rights: <span id="rights-output"></span></p>
</div>
</div>
## 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 |
<script src="/assets/js/rightsCalculator.js"></script>

37
docs/setup/server/systemd.md Normal file
View File

@ -0,0 +1,37 @@
# SystemD
Below is an example SystemD service for running Fosscord.
Save it in `/etc/systemd/system/fosscord.service`.
```toml
[Unit]
Description=Fosscord, for better and secure communication
[Service]
User=<your user>
WorkingDirectory=<fosscord directory>
ExecStart=npm run start
Restart=always
StandardError=journal
StandardOutput=journal
[Install]
WantedBy=multi-user.target
```
!!! error "Do not run Fosscord as the root user. This is a security risk to your system."
Make sure to edit the file as needed, such as replacing the user.
It is a good idea to create a new user on your system to run Fosscord.
If you would like to run the API, CDN or Gateway separately,
you can edit the `ExecStart` command used in line with the [npm script](npmScripts.md).
Also be sure to run [RabbitMQ](configuration/rabbitmq.md) in that case.
You can now start Fosscord using `sudo systemctl start fosscord`.
To automatically run Fosscord on boot, use `sudo systemctl enable fosscord`.
To view the server logs, you may use `journalctl -u fosscord`, or with `-f` to view them as they come.
You may also use the `lnav` package to get nice, colourised and scrolling output:
`journalctl -xefu fosscord | lnav`

19
docs/setup/server/updating.md Normal file
View File

@ -0,0 +1,19 @@
If you had followed the [setup guide](index.md), you'll have installed Fosscord using [Git](https://git-scm.com/).
Thus, you can update the server by running `git pull` in the `fosscord-server` directory.
If you had made any changes locally, you may run into merge conflicts,
where the Fosscord team has made changes to the same code you changed. If it's not important to you, you can simply run `git reset --hard HEAD`
_which will delete all your changes_. If you want to keep them, you'll have to go through each conflict and resolve them.
After downloading the new version, go through the setup guide as normal again:
```bash
# Install any new javascript packages
npm i
# Build and generate schema
npm run setup
# Start the server
npm run start
```

23
mkdocs.yml
View File

@ -1,22 +1,29 @@
site_name: Fosscord Docs site_name: Fosscord Documentation
repo_url: https://github.com/fosscord/fosscord repo_url: https://github.com/fosscord/fosscord
edit_uri: https://github.com/fosscord/fosscord-docs/edit/master/docs/ 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 site_description: "Documentation for Fosscord: a free open source selfhostable chat, voice and video discord-compatible platform"
plugins: plugins:
- section-index - section-index
- search - search
- render_swagger - swagger-ui-tag:
extra_css: [assets/swagger.css]
docExpansion: none
filter: true
theme: theme:
name: material name: material
logo: assets/logo.svg logo: assets/logo.svg
favicon: assets/logo.svg favicon: assets/favicon.svg
font: Open Sans font: Open Sans
palette: palette:
- scheme: default - media: "(prefers-color-scheme: light)"
primary: deep-orange
scheme: default
toggle: toggle:
icon: material/lightbulb-outline icon: material/lightbulb-outline
name: Switch to dark mode name: Switch to dark mode
- scheme: slate - media: "(prefers-color-scheme: dark)"
primary: deep-orange
scheme: slate
toggle: toggle:
icon: material/lightbulb icon: material/lightbulb
name: Switch to light mode name: Switch to light mode
@ -31,4 +38,8 @@ markdown_extensions:
- admonition - admonition
- pymdownx.details - pymdownx.details
- pymdownx.highlight - pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.superfences - pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
extra_css: [assets/extra.css]