Spacebar/docs
1
0
Fork 0
mirror of https://github.com/spacebarchat/docs.git synced 2024-11-22 18:22:31 +01:00
Code Issues Releases Activity

Merge pull request #62 from bitfl0wer/macros

Browse Source 
Replace "Fosscord" with macros and therefore enable simpler rebranding.
This commit is contained in:
Catalan Lover 2023-03-30 01:28:17 +02:00 committed by GitHub
commit 989ccbacdf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
32 changed files with 292 additions and 268 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -4,7 +4,7 @@
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/fosscord/fosscord-docs)
## How to get started:
## How to get started
1. Fork this repository.
2. Clone the forked repository.
@ -16,7 +16,7 @@
3. Install dependencies.
```bash
python3 -m pip install mkdocs-material mkdocs-swagger-ui-tag mkdocs-section-index
python3 -m pip install mkdocs-material mkdocs-swagger-ui-tag mkdocs-section-index mkdocs-macros-plugin
```
4. Edit documents(s).
@ -29,7 +29,7 @@
5. Test locally.
- Serve in http://127.0.0.1:8000 with hot reload:
- Serve in <http://127.0.0.1:8000> with hot reload:
```bash
python3 -m mkdocs serve

14
docs/contributing/conduct.md
View File

@ -1,18 +1,18 @@
# Code of Conduct
By contributing to or interacting with Fosscord or Fosscord community spaces, you accept the code of conduct.
By contributing to or interacting with {{ project.name }} or {{ project.name }} 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).
{{ project.name }} community spaces includes {{ project.name }} github repositories and {{ project.name }} development guilds (be it on Discord.com or {{ project.name }} instances mananged by the {{ project.name }} 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.
By contributing to any {{ project.name }} projects (for example, through pull request) you guarantee that you have the rights to resign all rights to {{ project.name }} under the AGPLV3 license.
### Desirable Behaviour
- If possible, provide assistance with Fosscord projects to other users.
- If possible, provide assistance with {{ project.name }} projects to other users.
- Be respectful toward other's opinions and viewpoints.
- Accepting responsibility and apologizing to those affected for our mistakes.
@ -27,7 +27,7 @@ By contributing to any Fosscord projects (for example, through pull request) you
- 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.
- Undesired automation of services that may lead to a reduction in service quality. For example, API spam of a {{ project.name }} 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.
@ -37,11 +37,11 @@ By contributing to any Fosscord projects (for example, through pull request) you
- 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.
- Kicks and bans apply to all communities administered by the {{ project.name }} 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.
You may report any violation of this code of conduct to the {{ project.name }} 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.

4
docs/contributing/index.md
View File

@ -4,7 +4,7 @@
## Style and a note on etiquette
- We use [prettier](https://www.npmjs.com/package/prettier) for code formatting. We have a `.prettierrc` file in fosscord-server's root
- We use [prettier](https://www.npmjs.com/package/prettier) for code formatting. We have a `.prettierrc` file in {{ project.name.lower() }}-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,
@ -16,7 +16,7 @@
## Structure
Fosscord is written in Typescript and is comprised of 4 main parts:
{{ project.name }} is written in Typescript and is comprised of 4 main parts:
- REST HTTP API server
- Websocket Gateway server for realtime communication with clients

2
docs/contributing/server/index.md
View File

@ -1,4 +1,4 @@
# Contributing to fosscord-server
# Contributing to {{ project.name.lower() }}-server
## [Migrations](migrations.md)

4
docs/contributing/server/migrations.md
View File

@ -8,14 +8,16 @@
## Generating Migrations
To generate a database migration in fosscord-server:
To generate a database migration in {{ project.name.lower() }}-server:
1. On the branch/commit you want to migrate _from_, generate the database.
You can run the server or run [`npm run sync:db`](../../setup/server/npmScripts.md#syncdb).
2. Switch to branch/commit you want to migrate _to_, and run
```
npm run generate:migration -- src/util/migrations/:dbms:/:migrationName:
```
where `:dbms:` is the db you use, and `:migrationName:` is whatever you wish to call it.
The migration must be named a valid Javascript class name.
3. The generated file is what TypeORM will do if you were to run `npm run sync:db`.

8
docs/contributing/server/missingroute.md
View File

@ -1,11 +1,11 @@
# Missing Routes
Below is a list of routes available on Discord.com Fosscord-server does not currently implement.
Below is a list of routes available on Discord.com {{ project.name }}-server does not currently implement.
It does not account for different HTTP methods (GET, POST, etc). A single method implemented by Fosscord will remove it from this list,
so be sure to double check in the Fosscord [source code](https://github.com/fosscord/fosscord-server/tree/master/src/api/routes).
It does not account for different HTTP methods (GET, POST, etc). A single method implemented by {{ project.name }} will remove it from this list,
so be sure to double check in the {{ project.name }} [source code]({{ repositories.base_url }}/{{ repositories.server }}/tree/master/src/api/routes).
It is generated daily by [fosscord/fosscord-missing-routes](https://github.com/fosscord/fosscord-missing-routes/),
It is generated daily by [{{ repositories.missing_routes }}]({{ repositories.base_url }}/{{ repositories.missing_routes }}/),
by scraping the latest Discord.com client.
<div>

40
docs/faq.md
View File

@ -3,33 +3,33 @@
??? info "How do you use the Client?"
As described in [Clients](/setup/clients), the official client is not ready yet. You are free to use
a Fosscord compatible client to connect, but no support will be provided.
a {{ project.name }} compatible client to connect, but no support will be provided.
??? info "Voice/Video when?"
Currently there is no voice or video support in any Fosscord instance.
Currently there is no voice or video support in any {{ project.name }} instance.
This is a very difficult feature to get working, especially given that
we must implement it the exact same way as Discord.com for client compatibility.
[We would be incredibly thankful for any assistance.](/contributing)
??? info "Free Nitro?"
Please do not use Discord trademarks to refer to anything regarding Fosscord.
Please do not use Discord trademarks to refer to anything regarding {{ project.name }}.
As an instance owner, you can grant yourself or others *premium* features which may be used to determine your abilities
*client-side*. However, Fosscord-server currently does not have any distinction between premium and free users.
*client-side*. However, {{ project.name }}-server currently does not have any distinction between premium and free users.
All users can access all features, given they have the [rights](setup/server/security/rights.md) to do so.
You cannot give yourself premium features on Discord.com using a Fosscord instance.
You cannot give yourself premium features on Discord.com using a {{ project.name }} instance.
??? info "How do I boost my guild? Or, how do I buy premium?"
You cannot buy premium features through Fosscord, as Fosscord does not support any payment backend.
You cannot buy premium features through {{ project.name }}, as {{ project.name }} does not support any payment backend.
Additionally, Fosscord does not currently have any distinction between premium and free users or guilds.
Additionally, {{ project.name }} 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.
if the user's `premium_type` or `premium` values are not set correctly. By default, {{ project.name }} 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.
@ -37,24 +37,24 @@
??? 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.
No. {{ project.name }} and Discord are entirely separate services, with their own separate databases
and authentication. {{ project.name }} 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?"
??? info "Does {{ project.name }} 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).
infrastructure. {{ project.name }} 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
If you mean Discord 'server' as in a *guild*, also no. {{ project.name }} is not a proxy for
Discord guilds. {{ project.name }} 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,
If {{ project.name }} 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).
Lastly, you can simply view [our codebase]({{ repositories.base_url }}/{{ repositories.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.
@ -63,17 +63,17 @@
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.
to ensure the {{ project.name }} codebase is free of any proprietary code. We want absolutely nothing to do with it.
??? 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 {{ project.name }} maintainers do not believe it to be, no. See: [Oracle v. Google](https://en.wikipedia.org/wiki/Google_LLC_v._Oracle_America,_Inc.).
??? 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.
3. {{ project.name }} 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.
@ -81,7 +81,7 @@
??? 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.
Currently no, there is no graphical interface for managing your {{ project.name }} instance.
An admin dashboard is planned, but we currently have higher priorities right now.
??? info "When will this feature be available?"

24
docs/index.md
View File

@ -6,30 +6,30 @@
!!! question "Have a question? It might be in [here](faq.md)"
## What is Fosscord?
## What is {{ project.name }}?
Fosscord is a Discord.com server implementation and extension,
{{ project.name }} is a Discord.com server implementation and extension,
with the goal of complete feature parity with Discord.com,
all while adding some additional goodies, security, privacy, and configuration options.
Fosscord allows you to host a complete, Discord.com-compatible chat service
{{ project.name }} allows you to host a complete, Discord.com-compatible chat service
with complete control over it's content, usage, security, configuration, and featureset.
Being Discord.com-compatible 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
Discord.com to be used on any {{ project.name }} instance, which we believe will be immensely useful
for any transition process between services.
As Fosscord is an entirely separate service from Discord.com, it means a Fosscord server by itself **cannot**
access private data controlled by Discord.com. You **cannot** use a Fosscord server to chat with your friends on Discord.com.
You also **cannot** use a Fosscord server to grant premium ("Nitro") features to a Discord.com account (although you can grant these to a Fosscord account).
As {{ project.name }} is an entirely separate service from Discord.com, it means a {{ project.name }} server by itself **cannot**
access private data controlled by Discord.com. You **cannot** use a {{ project.name }} server to chat with your friends on Discord.com.
You also **cannot** use a {{ project.name }} server to grant premium ("Nitro") features to a Discord.com account (although you can grant these to a {{ project.name }} account).
Our goal is to achieve complete feature parity with Discord.com, as well as
implement additional security, privacy, and other useful features serverside.
In addition to our server software, we aim to create Fosscord-aware clients that can be used to connect
to multiple Fosscord-compatible instances with rich theming and plugin support.
In addition to our server software, we aim to create {{ project.name }}-aware clients that can be used to connect
to multiple {{ project.name }}-compatible instances with rich theming and plugin support.
## Support
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).
For any kind of support regarding {{ project.name }}, feel free to ask questions in our [Discord.com server](https://discord.gg/Ms5Ev7S6bF)
or our [official {{ project.name }} instance](https://staging.{{ project.domain }}).
For bug reporting and feature requests please create an [issue](https://github.com/fosscord/fosscord-server/issues/new/choose) on Github.
For bug reporting and feature requests please create an [issue]({{ repositories.base_url }}/{{ repositories.server }}/issues/new/choose) on Github.

2
docs/routes.md
View File

@ -6,5 +6,5 @@
}
</style>
<swagger-ui src="https://raw.githubusercontent.com/fosscord/fosscord-server/master/assets/openapi.json"/>
<swagger-ui src="https://raw.githubusercontent.com/{{ repositories.server }}/master/assets/openapi.json"/>
<!-- <swagger-ui src="/assets/openapi.json"/> -->

16
docs/setup/bots/index.md
View File

@ -1,11 +1,11 @@
# Bots and Applications
Fosscord is backwards-compatibile with Discord.com, and so all
{{ project.name }} 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.
when connected to a {{ project.name }} 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.
to create bots and applications on a {{ project.name }} instance as Discord.com.
## Bot Libraries
@ -20,9 +20,9 @@ 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",
api: "https://api.{{ project.domain }}",
cdn: "https://cdn.{{ project.domain }}",
invite: "https://{{ project.domain }}/invite",
},
});
@ -34,7 +34,7 @@ client.login("your token here");
```py
import discord
discord.http.Route.BASE = "https://api.fosscord.com"
discord.http.Route.BASE = "https://api.{{ project.domain }}"
client = discord.Client()
client.run('your token here')
@ -56,6 +56,6 @@ public static void main(String[] args) {
modifiers.setAccessible(true);
modifiers.setString(field, field.getModifiers() & ~Modifier.FINAL);
field.set(null, "https://api.fosscord.com");
field.set(null, "https://api.{{ project.domain }}");
}
```

31
docs/setup/clients/index.md
View File

@ -1,25 +1,26 @@
# Clients
!!! note "The Fosscord client is, at the time of writing this (March 17th, 2023), under heavy development and not ready to be used in production just yet."
!!! note "The {{ project.name }} client is, at the time of writing this (March 17th, 2023), under heavy development and not ready to be used in production just yet."
!!! warning "Windows support is currently broken."
The official Fosscord client is currently being developed at [this repository](https://github.com/fosscord/fosscord-client/tree/dev/bare-rewrite).
The official {{ project.name }} client is currently being developed at [this repository]({{ repositories.base_url }}/{{ repositories.client }}/tree/dev/bare-rewrite).
## Official host
We currently host the client at [https://app.fosscord.com](https://app.fosscord.com).
We currently host the client at [https://app.{{ project.domain }}](https://app.{{ project.domain }}).
You can use it to connect to our official instance by default,
or you can use it to connect to your own by editing your local storage to include the `routeSettings` key with the below example content:
```json
{
"api":"https://staging.fosscord.com/api/v9",
"cdn":"https://cdn.staging.fosscord.com",
"gateway":"wss://gateway.staging.fosscord.com",
"invite":"https://staging.fosscord.com/invite",
"template":"https://staging.fosscord.com/template",
"gift":"https://staging.fosscord.com/gift",
"scheduledEvent":"https://staging.fosscord.com/events"
"api":"https://staging.{{ project.domain }}/api/v9",
"cdn":"https://cdn.staging.{{ project.domain }}",
"gateway":"wss://gateway.staging.{{ project.domain }}",
"invite":"https://staging.{{ project.domain }}/invite",
"template":"https://staging.{{ project.domain }}/template",
"gift":"https://staging.{{ project.domain }}/gift",
"scheduledEvent":"https://staging.{{ project.domain }}/events"
}
```
@ -37,11 +38,11 @@ Replace the above endpoints with your own. If your domain name is `https://whate
In your terminal:
```bash
# Download Fosscord Client
git clone https://github.com/fosscord/fosscord-client.git
# Download {{ project.name }} Client
git clone {{ repositories.base_url }}/{{ repositories.client }}.git
# Enter the cloned directory, switch branches to the one, which is actually being developed
cd fosscord-client; git switch dev/bare-rewrite
cd {{ project.name.lower() }}-client; git switch dev/bare-rewrite
# Install dependencies
yarn install
@ -85,7 +86,7 @@ Files will be built to `web-build`
To contribute:
- [Fork the repository](https://github.com/fosscord/fosscord-client/fork)
- [Fork the repository]({{ repositories.base_url }}/{{ repositories.client }}/fork)
- Run the building instructions.
- Commit & Push.
- Pull Request & Done!
@ -94,4 +95,4 @@ To contribute:
- "Core" features like settings, editing messages, dms, markdown rendering, etc. What do you think are basic features that you would want? Some of the GitHub Issues apply to this.
- Implementing other things like voice/video is fine too, though
- [This](https://github.com/fosscord/fosscord-client/issues/21) is a good starting point and lists the core features that are still missing from the client.
- [This]({{ repositories.base_url }}/{{ repositories.client }}/issues/21) is a good starting point and lists the core features that are still missing from the client.

4
docs/setup/server/configuration/embeds.md
View File

@ -1,7 +1,7 @@
# 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,
Embeds in {{ project.name }} are external content that is displayed within your messages when linked to.
{{ project.name }} 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.

6
docs/setup/server/configuration/env.md
View File

@ -1,12 +1,12 @@
# Environment Variables
Below is a list of environment variables used by Fosscord.
Below is a list of environment variables used by {{ project.name }}.
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.
in the `{{ project.name.lower() }}-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 |
| THREADS | number | Number of threads to run {{ project.name }} 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 |

2
docs/setup/server/configuration/guildFeatures.md
View File

@ -2,7 +2,7 @@
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.
In {{ project.name }}, 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)

16
docs/setup/server/configuration/imagor.md
View File

@ -1,8 +1,8 @@
# 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
used by {{ project.name }} for external image resizing, primarily by embeds from other websites when linked in a message.
If left unused, {{ project.name }} 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.
@ -12,12 +12,12 @@ privacy concerns, as an attacker may be able to learn users IP addresses.
## Setup
To setup Imagor for Fosscord, first grab the `security_requestSignature` config value from Fosscord's database,
To setup Imagor for {{ project.name }}, first grab the `security_requestSignature` config value from {{ project.name }}'s database,
and create a `imagor.env` file somewhere safe, with the following content.
**Make sure to edit the file with the correct information**. Your requestSignture should _not_ start or end with `"`.
```
IMAGOR_SECRET=security_requestSignature value from your Fosscord config
IMAGOR_SECRET=security_requestSignature value from your {{ project.name }} config
PORT=8000
```
@ -31,7 +31,7 @@ docker run --env-file ./imagor.env -p 8000:8000 shumc/imagor
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
If you're using a [reverse proxy](../reverseProxy.md) such as Nginx for {{ project.name }} already, you could add this to your config's `server` block
```nginx
location /media/ {
@ -62,10 +62,10 @@ Alternative (and perhaps the better choice) would be to create a new domain, say
}
```
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.
Our last step is to simply tell {{ project.name }} about Imagor. Just set the `cdn_imagorServerUrl` config value to your public endpoint for Imagor, wrapped in quotes.
For example, if you used the `/media` location in your existing nginx config, it will look something like `"https://your.fosscord.com/media"`.
If you used a subdomain, it will look like `"https://media.your.fosscord.com"`.
For example, if you used the `/media` location in your existing nginx config, it will look something like `"https://your.{{ project.domain }}/media"`.
If you used a subdomain, it will look like `"https://media.your.{{ project.domain }}"`.
Don't include a trailing backslash.
Congrats! After a restart, you've now got Imagor resizing your images!

22
docs/setup/server/configuration/index.md
View File

@ -1,11 +1,11 @@
# Configuration
Fosscord's configuration is done through the `config` table of your [database](../database.md).
{{ project.name }}'s configuration is done through the `config` table of your [database](../database.md).
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."
!!! note "The `CONFIG_PATH` [environment variable](env.md) can be set to make {{ project.name }} use a JSON file instead of a database table."
## Array Types
@ -23,16 +23,16 @@ Arrays are represented by \_[number] in a config key. For example, multiple `gui
| -------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------- |
| gateway_endpointPrivate | null | string | Used for internal communication with gateway |
| gateway_endpointPublic | null | string | Publicly announced gateway endpoint |
| cdn_endpointPrivate | http://localhost:3001 | string | See gateway_endpointPrivate |
| cdn_endpointPublic | http://localhost:3001 | string | See gateway_endpointPublic |
| 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). |
| api_endpointPublic | "/api" | string | See gateway_endpointPublic |
| 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_instanceName | {{ project.name }} Instance | string | Announced instance name |
| general_instanceDescription | This is a {{ project.name }} 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 |
@ -87,7 +87,7 @@ Arrays are represented by \_[number] in a config key. For example, multiple `gui
| 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_ipdataApiKey | {{ project.name }} 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 |
@ -112,10 +112,10 @@ Arrays are represented by \_[number] in a config key. For example, multiple `gui
| 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) | 875069521787904 | string | The rights assigned to users _upon registration_ |
| regions_default | fosscord | string | The default voice region to use |
| regions_default | {{ project.name.lower() }} | 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_id | {{ project.name.lower() }} | string[] | The available voice region IDs |
| regions_available_0_name | {{ project.name }} | 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) |
@ -134,7 +134,7 @@ Arrays are represented by \_[number] in a config key. For example, multiple `gui
| 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 |
| sentry_enabled | false | boolean | Whether server-side Sentry analytics is enabled |
| sentry_endpoint | Fosscord sentry endpoint | string | Sentry endpoint |
| sentry_endpoint | {{ project.name }} 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 |

6
docs/setup/server/configuration/rabbitmq.md
View File

@ -1,14 +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.
{{ project.name }} 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"`
edit {{ project.name }}'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,
If you want to run {{ project.name }} over multiple systems,
you'll need to set up [access control](https://www.rabbitmq.com/access-control.html) in RabbitMQ.

4
docs/setup/server/database.md
View File

@ -1,11 +1,11 @@
# Database
By default, Fosscord will use SQLite. SQLite is nice for testing or development,
By default, {{ project.name }} 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)
but to configure {{ project.name }} 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

20
docs/setup/server/email.md
View File

@ -1,32 +1,32 @@
# Email
Fosscord can be configured to send email, to enable the following functionality:
{{ project.name }} can be configured to send email, to enable the following functionality:
- Email verification
- Password resets
- Password change notifications
Fosscord supports the following email transports:
{{ project.name }} supports the following email transports:
- SMTP
- [Mailjet](https://www.mailjet.com/)
- [Mailgun](https://www.mailgun.com/)
- [Sendgrid](https://sendgrid.com/)
Once you have an account with one of the above services, or an SMTP service, you can begin configuring Fosscord to send mail.
Once you have an account with one of the above services, or an SMTP service, you can begin configuring {{ project.name }} to send mail.
You must edit:
* The `general_frontPage` [config](configuration/index.md) value, used to generate verification/password reset links.
Be sure to set it to the Fosscord web app URL. For example, `https://staging.fosscord.com`
* The `general_correspondenceEmail` config value, used as the 'from' email address.
- The `general_frontPage` [config](configuration/index.md) value, used to generate verification/password reset links.
Be sure to set it to the {{ project.name }} web app URL. For example, `https://staging.{{ project.domain }}`
- The `general_correspondenceEmail` config value, used as the 'from' email address.
If unset, `noreply@localhost` is used, which will most likely throw an error with your email service.
Optionally:
* By default users are automatically verified. To change this, update the `defaults_user_verified` [config](configuration/index.md) value to `false`.
* If you would like users to be forced to verify their email before using the service, set the `login_requireVerification` config to `true`.
* You may force users to pass a CAPTCHA before requesting a password reset by setting `passwordReset_requireCaptcha` to `true`
- By default users are automatically verified. To change this, update the `defaults_user_verified` [config](configuration/index.md) value to `false`.
- If you would like users to be forced to verify their email before using the service, set the `login_requireVerification` config to `true`.
- You may force users to pass a CAPTCHA before requesting a password reset by setting `passwordReset_requireCaptcha` to `true`
## Email Config
@ -62,7 +62,7 @@ Optionally:
## Email templates
Fosscord's email templates are stored in [`fosscord-server/assets/email_templates`](https://github.com/fosscord/fosscord-server/tree/master/assets/email_templates).
{{ project.name }}'s email templates are stored in [`{{ project.name.lower() }}-server/assets/email_templates`]({{ repositories.base_url }}/{{ repositories.server }}/tree/master/assets/email_templates).
They are simple HTML files, which you may edit freely. Although HTML mail is very restricted, so a lot of content may not render properly.
Below are the available strings replaced in mail templates.

16
docs/setup/server/index.md
View File

@ -1,15 +1,15 @@
# Server Setup
Fosscord-server setup ranges in difficulty depending on how you want to configure your system.
{{ project.name }}-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.
We do **not** recommend or support running {{ project.name }} 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.
We do not recommend using Windows to run {{ project.name }}.
## Dependencies
@ -26,11 +26,11 @@ We do not recommend using Windows to run Fosscord.
In your terminal:
```bash
# Download Fosscord
git clone https://github.com/fosscord/fosscord-server.git
# Download {{ project.name }}
git clone {{ repositories.base_url }}/{{ repositories.server }}.git
# Navigate to project root
cd fosscord-server
cd {{ project.name.lower() }}-server
# Install javascript packages
npm i
@ -42,14 +42,14 @@ npm run setup
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 all went according to plan, you can now access your new {{ project.name }} 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!
Well, now you can configure {{ project.name }} to your liking!
- [Skip to server configuration](configuration)
- [Skip to reverse proxy / SSL](reverseProxy.md)

2
docs/setup/server/maintenance/index.md
View File

@ -2,4 +2,4 @@
## [When do I have to restart the server?](restart.md)
## [Updating Fosscord-server](updating.md)
## [Updating {{ project.name }}-server](updating.md)

2
docs/setup/server/maintenance/restart.md
View File

@ -1,6 +1,6 @@
# When must the server restart?
Fosscord-server must restart in the following cases:
{{ project.name }}-server must restart in the following cases:
- The .env file or config (database or [CONFIG_PATH](/setup/server/configuration) has changed.
- Files in the `client_test`, `preload-plugins` folders of inside `assets` have changed.

6
docs/setup/server/maintenance/updating.md
View File

@ -1,8 +1,8 @@
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 followed the [setup guide](index.md), you'll have installed {{ project.name }} using [Git](https://git-scm.com/).
Thus, you can update the server by running `git pull` in the `{{ project.name.lower() }}-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`
where the {{ project.name }} 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:

10
docs/setup/server/migatingFromStaging.md
View File

@ -1,15 +1,15 @@
# 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).
'Staging' refers to [this branch]({{ repositories.base_url }}/{{ repositories.server }}/tree/staging) of {{ project.name.lower() }}-server,
which is deprecated in favour of [the refactor branch]({{ repositories.base_url }}/{{ repositories.server }}/tree/maddy/refactor) (if this is a 404, its just become the main branch now).
!!! warning "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.
1. Download the new version of {{ project.name.lower() }}-server
`git clone {{ repositories.base_url }}/{{ repositories.server }}.git`
2. Copy your `.env` file from your previous installation to the new `{{ project.name.lower() }}-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`

8
docs/setup/server/npmScripts.md
View File

@ -8,12 +8,12 @@ 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.
Syncronise the database schema between {{ project.name }} source code and your database.
**May incur data loss**. You do not normally need to run this script, as {{ project.name }}-server will perform it when necessary.
## `build`
Builds the Fosscord source code
Builds the {{ project.name }} source code
## `start`
@ -30,4 +30,4 @@ Also displays the 'all rights' value, which `1` is a placeholder for.
## `generate:schema`
Recreates the `fosscord-server/assets/schema.json` file, which is used for API and Gateway request validation.
Recreates the `{{ project.name.lower() }}-server/assets/schema.json` file, which is used for API and Gateway request validation.

12
docs/setup/server/reverseProxy.md
View File

@ -2,10 +2,10 @@
## NGINX
Generally, our community sets up Fosscord instances behind NGINX, a powerful reverse proxy.
Generally, our community sets up {{ project.name }} instances behind NGINX, a powerful reverse proxy.
Below is an example NGINX config. On Ubuntu, you can put this in the `/etc/nginx/sites-available/fosscord.conf` file,
and enable it with `ln -s /etc/nginx/sites-available/fosscord.conf /etc/nginx/sites-enabled/` and `systemctl restart nginx`
Below is an example NGINX config. On Ubuntu, you can put this in the `/etc/nginx/sites-available/{{ project.name.lower() }}.conf` file,
and enable it with `ln -s /etc/nginx/sites-available/{{ project.name.lower() }}.conf /etc/nginx/sites-enabled/` and `systemctl restart nginx`
!!! info
@ -16,11 +16,11 @@ and enable it with `ln -s /etc/nginx/sites-available/fosscord.conf /etc/nginx/si
```nginx
server {
# Change server_name
server_name fosscord.example.com;
server_name {{ project.name.lower() }}.example.com;
listen 80;
location / {
# Only change this if Nginx and Fosscord are not on the same machine.
# Only change this if Nginx and {{ project.name }} are not on the same machine.
proxy_pass http://127.0.0.1:3001;
proxy_set_header Host $host;
proxy_pass_request_headers on;
@ -71,7 +71,7 @@ After you've set up NGINX, it's very simple to also set up SSL using `certbot`.
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!
After which, you should now have a SSL secured {{ project.name }} 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`).

4
docs/setup/server/security/captcha.md
View File

@ -1,6 +1,6 @@
# CAPTCHAs
Fosscord currently supports two CAPTCHA providers; reCAPTCHA and hCaptcha.
{{ project.name }} currently supports two CAPTCHA providers; reCAPTCHA and hCaptcha.
=== "hCaptcha"
@ -16,7 +16,7 @@ Fosscord currently supports two CAPTCHA providers; reCAPTCHA and hCaptcha.
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.
4. Add your domain. For example, `staging.{{ project.domain }}`. 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"`

2
docs/setup/server/security/limits.md
View File

@ -1,6 +1,6 @@
# 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)
{{ project.name }} 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_*`)

2
docs/setup/server/security/regTokens.md
View File

@ -25,5 +25,5 @@ There are a few query parameters available. Append them to the request URL, for
To use a registration token, append `?token={your registration token}` to the register route. For example
```
https://staging.fosscord.com/register?token=some token
https://staging.{{ project.domain }}/register?token=some token
```

20
docs/setup/server/systemd.md
View File

@ -1,15 +1,15 @@
# SystemD
Below is an example SystemD service for running Fosscord.
Save it in `/etc/systemd/system/fosscord.service`.
Below is an example SystemD service for running {{ project.name }}.
Save it in `/etc/systemd/system/{{ project.name.lower() }}.service`.
```toml
[Unit]
Description=Fosscord, for better and secure communication
Description={{ project.name }}, for better and secure communication
[Service]
User=<your user>
WorkingDirectory=<fosscord directory>
WorkingDirectory=<{{ project.name.lower() }} directory>
ExecStart=npm run start
Restart=always
StandardError=journal
@ -19,19 +19,19 @@ StandardOutput=journal
WantedBy=multi-user.target
```
!!! error "Do not run Fosscord as the root user. This is a security risk to your system."
!!! error "Do not run {{ project.name }} 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.
It is a good idea to create a new user on your system to run {{ project.name }}.
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`.
You can now start {{ project.name }} using `sudo systemctl start {{ project.name.lower() }}`.
To automatically run Fosscord on boot, use `sudo systemctl enable fosscord`.
To automatically run {{ project.name }} on boot, use `sudo systemctl enable {{ project.name.lower() }}`.
To view the server logs, you may use `journalctl -u fosscord`, or with `-f` to view them as they come.
To view the server logs, you may use `journalctl -u {{ project.name.lower() }}`, 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`
`journalctl -xefu {{ project.name.lower() }} | lnav`

28
mkdocs.yml
View File

@ -1,10 +1,30 @@
site_name: Fosscord Documentation
repo_url: https://github.com/fosscord/fosscord
edit_uri: https://github.com/fosscord/fosscord-docs/edit/master/docs/
site_description: "Documentation for Fosscord: a free open source selfhostable chat, voice and video discord-compatible platform"
extra:
#
# Change these macros if you wish to update the projects' name.
# Use {{ variable_name }} in .md files to reference a variable that you've declared here.
# For more information, read https://mkdocs-macros-plugin.readthedocs.io/en/latest/ .
#
project:
name: Fosscord # Tip: use {{ project_name.lower() }} to get the project name in lowercase.
domain: fosscord.com
repositories:
base_url: https://github.com/
server: fosscord/fosscord-server
client: fosscord/fosscord-client
missing_routes: fosscord/fosscord-missing-routes
main: &repo_url https://github.com/fosscord/fosscord # This gets read by mkdocs without being pre-proccessed by mkdocs-macros, which is why the URL is in full.
site:
name: &site_name Fosscord Documentation
description: &site_description "Documentation for Fosscord: a free open source selfhostable chat, voice and video discord-compatible platform"
edit_uri: &edit_uri https://github.com/fosscord/fosscord-docs/edit/master/docs/ # This gets read by mkdocs without being pre-proccessed by mkdocs-macros, which is why the URL is in full.
site_name: *site_name
repo_url: *repo_url
edit_uri: *edit_uri
site_description: *site_description
plugins:
- section-index
- search
- macros
- swagger-ui-tag:
extra_css: [assets/swagger.css]
docExpansion: none

1
requirements.txt
View File

@ -2,3 +2,4 @@ mkdocs
mkdocs-material
mkdocs-swagger-ui-tag
mkdocs-section-index
mkdocs-macros-plugin