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

Merge branch 'master' of github.com:spacebarchat/docs

Browse Source
This commit is contained in:
Madeline 2023-11-20 19:32:16 +11:00
commit 34561e6d5a
No known key found for this signature in database
GPG Key ID: 80D25DA3BCB24281
27 changed files with 325 additions and 214 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/build.yml vendored
View File

@ -1,5 +1,6 @@
name: Build to GitHub Pages name: Build to GitHub Pages
on: on:
workflow_dispatch:
push: push:
branches: branches:
- master - master
@ -12,7 +13,8 @@ jobs:
- uses: actions/setup-python@v2 - uses: actions/setup-python@v2
with: with:
python-version: 3.x python-version: 3.x
- run: python3 -m pip install mkdocs-material mkdocs-swagger-ui-tag mkdocs-section-index mkdocs-macros-plugin - run: curl https://raw.githubusercontent.com/spacebarchat/spacebarchat/master/CODE_OF_CONDUCT.md -o docs/contributing/conduct.md
- run: python3 -m pip install -r requirements.txt
- run: mkdocs build - run: mkdocs build
- run: echo docs.spacebar.chat >> site/CNAME - run: echo docs.spacebar.chat >> site/CNAME
- name: Deploy 🚀 - name: Deploy 🚀

6
README.md
View File

@ -1,6 +1,8 @@
# Spacebar Docs # Spacebar Docs
[![Build to GitHub Pages](https://github.com/spacebarchat/docs/actions/workflows/build.yml/badge.svg)](https://github.com/spacebarchat/docs/actions/workflows/build.yml) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![Build to GitHub Pages](https://github.com/spacebarchat/docs/actions/workflows/build.yml/badge.svg)](https://github.com/spacebarchat/docs/actions/workflows/build.yml)
[![Netlify Status](https://api.netlify.com/api/v1/badges/86622c9d-4952-4da5-9825-cc016e4a5e5f/deploy-status)](https://app.netlify.com/sites/spacebar-chat/deploys)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/spacebarchat/docs) [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/spacebarchat/docs)
@ -16,7 +18,7 @@
3. Install dependencies. 3. Install dependencies.
```bash ```bash
python3 -m pip install mkdocs-material mkdocs-swagger-ui-tag mkdocs-section-index mkdocs-macros-plugin python3 -m pip install -r requirements.txt
``` ```
4. Edit documents(s). 4. Edit documents(s).

11
docs/assets/js/missingroutes.js
View File

@ -16,7 +16,16 @@ document
(async () => { (async () => {
const res = await fetch(MISSING_ROUTES_LIST); const res = await fetch(MISSING_ROUTES_LIST);
const missingRoutes = await res.json(); const json = await res.json();
const missingRoutes = json.routes;
document.getElementById("counter").innerHTML =
`We implement ${json.discord - json.missing}/${
json.discord
} endpoints from Discord.com ` +
`as well as ${
json.spacebar + json.missing - json.discord
} additional endpoints.`;
for (let route of missingRoutes) { for (let route of missingRoutes) {
const elem = document.createElement("li"); const elem = document.createElement("li");

31
docs/assets/overrides/routes.html Normal file
View File

@ -0,0 +1,31 @@
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
</head>
<body>
<rapi-doc
spec-url = "https://raw.githubusercontent.com/spacebarchat/server/master/assets/openapi.json"
theme="dark"
sort-endpoints-by="none"
header-color="#4051b5"
primary-color="#4051b5"
render-style="focused"
schema-expand-level=1
schema-style="table"
default-schema-tab="schema"
show-components="true"
heading-text="Spacebar HTTP API Documentation"
show-curl-before-try="true"
allow-spec-url-load="false"
allow-spec-file-load="false"
>
<a slot="logo" href="https://docs.spacebar.chat" style="margin-left: 20px; width: 30px; height: 30px;">
<img style="width: 30px; height: 30px;" src="https://docs.spacebar.chat/assets/logo.svg" />
</a>
</body>
</html>

3
docs/assets/swagger.css
View File

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

51
docs/contributing/conduct.md
View File

@ -1,51 +0,0 @@
# 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.
{{ 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 {{ 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 {{ project.name }} 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 {{ 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.
### 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 {{ project.name }} maintainers group.
### Reporting problems
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.
### 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**

5
docs/contributing/instances.md
View File

@ -1,6 +1,6 @@
# For Instance Owners # For Instance Owners
The below are the rules for instance owners who look to be featured in our [community instances](https://github.com/spacebarchat/community-instances) list. The below are the rules for instance owners who look to be featured in our [community instances](https://github.com/spacebarchat/spacebarchat/tree/master/instances) list.
If you do not meet these criteria, your instance will simply not be featured on our website. If you do not meet these criteria, your instance will simply not be featured on our website.
Your instance: Your instance:
@ -13,6 +13,7 @@ Your instance:
6. Must have a valid and monitored [`general_correspondenceEmail` config](/setup/server/configuration) set. 6. Must have a valid and monitored [`general_correspondenceEmail` config](/setup/server/configuration) set.
7. Must not have default [rights](/setup/server/security/rights) that include operator or other administrative rights. 7. Must not have default [rights](/setup/server/security/rights) that include operator or other administrative rights.
8. Enable [Imagor](/setup/server/configuration/imagor), as no image proxy allows attackers to learn user IP addresses. 8. Enable [Imagor](/setup/server/configuration/imagor), as no image proxy allows attackers to learn user IP addresses.
9. Have a valid SSL/TLS certificate for all endpoints.
We recommend (not required) that you: We recommend (not required) that you:
@ -21,3 +22,5 @@ We recommend (not required) that you:
- Run your instance under [SystemD](/setup/server/systemd) or a similar system in your distro, for automatic restarting - Run your instance under [SystemD](/setup/server/systemd) or a similar system in your distro, for automatic restarting
- Provide some mechanism for users to report content. This may be as simple as more openly advertising your correspondence email (i.e. outside `GET /api/policies/instance` or `/api/ping`) - Provide some mechanism for users to report content. This may be as simple as more openly advertising your correspondence email (i.e. outside `GET /api/policies/instance` or `/api/ping`)
- Provide some mechanism for instance status, such as [Grafana](https://grafana.com/). - Provide some mechanism for instance status, such as [Grafana](https://grafana.com/).
- Host a [`/.well-known/spacebar`](/setup/server/wellknown) file on the domain you wish users associate with your instance, e.g. `spacebar.chat`.
If doing so, use this domain as the `url` field in your community instances PR.

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

@ -9,15 +9,16 @@ It is generated daily by [{{ repositories.missing_routes }}]({{ repositories.bas
by scraping the latest Discord.com client. by scraping the latest Discord.com client.
<div> <div>
<div class="fc-search"> <div class="fc-search">
<input <input
id="missing-routes-search" id="missing-routes-search"
class="md-input md-input--stretch" class="md-input md-input--stretch"
placeholder="Search missing routes" placeholder="Search missing routes"
/> />
</div> </div>
<ul id="missing-routes-list"> <p id="counter"></p>
</ul> <ul id="missing-routes-list">
</ul>
</div> </div>
<script src="/assets/js/missingroutes.js"></script> <script src="/assets/js/missingroutes.js"></script>

24
docs/faq.md
View File

@ -1,5 +1,29 @@
# Frequently Asked Questions # Frequently Asked Questions
??? info "Is {{ project.name }} still in development? Production Ready?"
Yes, {{ project.name }} is still in development. Our unpaid team of volunteers is very small though, and so progress is very dependant on our motivation
and outside life.
The [{{ project.name }} server]({{ repositories.base_url }}/{{ repositories.server }}) program has been in development since at least 28/11/2020,
and has most core features implemented. API compatibility is reasonable although not quite perfect and so some third party clients may not function,
although the official Discord.com client which we test against functions correctly for the most part.
The big Discord.com features currently left unimplemented or with partial implementations are:
* Voice/Video support
* Voice activities
* OAuth2 scopes and other applications (Bot applications work by are left unscoped)
* Message threads
* Pomelo (new username system without discriminators)
* Auto moderation
For a more complete overview of what is left unimplemented, please refer to [the missing routes viewer](./contributing/server/missingroute.md)
The [{{ project.name }} client]({{ repositories.base_url }}/{{ repositories.client }}) however is very premature, starting development around 1/03/2023.
It is not ready production use or as your daily driver. It lacks many core features and is not recommended to be used.
Please setup a third party client, or help contribute to our codebase! Any and all help is appreciated.
??? info "How do you use the Client?" ??? 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 As described in [Clients](/setup/clients), the official client is not ready yet. You are free to use

14
docs/routes.md
View File

@ -1,10 +1,4 @@
# API Routes ---
title: HTTP API Docs
<style> template: routes.html
#api-routes, .md-sidebar--secondary { ---
display: none !important;
}
</style>
<swagger-ui src="https://raw.githubusercontent.com/{{ repositories.server }}/master/assets/openapi.json"/>
<!-- <swagger-ui src="/assets/openapi.json"/> -->

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

@ -1,98 +1 @@
# Clients ## [Official Client](official)
!!! 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 {{ 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.{{ 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.{{ 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"
}
```
Replace the above endpoints with your own. If your domain name is `https://whatever.notasite`, then you'll most likely want to enter
`https://whatever.noasite/api/v9` for the API endpoint, etc.
## Setup/Building
### Dependencies
- [Git](https://git-scm.com/)
- [NodeJS](https://nodejs.org). Version 16+
- [yarn](https://yarnpkg.com/) (preferred) or npm
In your terminal:
```bash
# 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 {{ project.name.lower() }}-client; git switch dev/bare-rewrite
# Install dependencies
yarn install
```
To start the client with Metro for development, run
```bash
yarn start
```
!!! note "Platform-specific development commands:"
For development for Android, run
```bash
yarn android
```
For development for iOS, run
```bash
yarn ios
```
For development for Windows, run
```bash
yarn windows
```
To build static files for the web (i.e. when hosting it yourself), run
```bash
yarn build:web
```
Files will be built to `web-build`
## Contributing
To contribute:
- [Fork the repository]({{ repositories.base_url }}/{{ repositories.client }}/fork)
- Run the building instructions.
- Commit & Push.
- Pull Request & Done!
### What can I 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]({{ repositories.base_url }}/{{ repositories.client }}/issues/21) is a good starting point and lists the core features that are still missing from the client.

6
docs/setup/clients/official/index.md Normal file
View File

@ -0,0 +1,6 @@
# {{ project.name }} Client
The {{ project.name }} client has 2 versions:
- The new, React version which is currently under active development. Docs: [React Client](react.md)
- The old, legacy React Native version which is no longer under active development. Docs: [Legacy Client](legacy.md)

87
docs/setup/clients/official/legacy.md Normal file
View File

@ -0,0 +1,87 @@
# Legacy Client
!!! danger "This version is no longer under active development! Please see [React Client](dev.md) for the current in-development version."
!!! warning "Windows support is currently broken."
## Official host
The client will connect to our official instance by default, or you can use it to connect to your
own instance by editing your local storage to include the `routeSettings` key with the below example
content:
```json
{
"api": "https://api.old.server.{{ project.domain }}/api/v9",
"cdn": "https://cdn.old.server.{{ project.domain }}",
"gateway": "wss://gateway.old.server.{{ project.domain }}",
"invite": "https://old.server.{{ project.domain }}/invite",
"template": "https://old.server.{{ project.domain }}/template",
"gift": "https://old.server.{{ project.domain }}/gift",
"scheduledEvent": "https://old.server.{{ project.domain }}/events"
}
```
Replace the above endpoints with your own. If your domain name is `https://example.com`, then you'll most likely want to enter
`https://example.com/api/v9` for the API endpoint, etc.
You can also edit these settings by visiting `https://client.example.com/settings`
## Setup/Building
### Dependencies
- [Git](https://git-scm.com/)
- [NodeJS](https://nodejs.org). Version 18+
- [yarn](https://yarnpkg.com/)
In your terminal:
```bash
# Download {{ project.name }} Client
git clone {{ repositories.base_url }}/{{ repositories.client }}.git -b legacy-v2
# Enter the cloned directory
cd client
# Install dependencies
yarn install
```
To start the client with Metro for development, run
```bash
yarn start
```
!!! note "Platform-specific development commands:"
For development for Android, run
```bash
yarn android
```
For development for iOS, run
```bash
yarn ios
```
For development for Windows, run
```bash
yarn windows
```
To build static files for the web (i.e. when hosting it yourself), run
```bash
yarn build:web
```
Files will be built to `web-build`. These files need to be served by a Web Server such as Nginx or Apache, the `index.html` file cannot just be opened in a browser.
## Contributing
This version is no longer being developed, you are free to clone the repository and make your own changes though!

71
docs/setup/clients/official/react.md Normal file
View File

@ -0,0 +1,71 @@
# React Client
!!! warning "The {{ project.name }} client is under heavy development and not ready to be used in production yet."
The official {{ project.name }} client is currently being developed at [this repository]({{ repositories.base_url }}/{{ repositories.client }}).
## Official host
The client is currently hosted 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 instance by editing the `Instance` field on the login page.
!!! note
If you've set up [wellknown](/setup/server/wellknown/), you can enter that address here.
I.e. `https://spacebar.chat`. If you haven't, you'll need to enter the API endpoint address
!!! warning
If you're using the app at [https://app.{{ project.domain }}](https://app.{{ project.domain }}),
you'll need to make sure your instance allows CORS from that address.
## Setup/Building
### Dependencies
- [Git](https://git-scm.com/)
- [NodeJS](https://nodejs.org): Version 18+
- [pnpm](https://pnpm.io/)
In your terminal:
```bash
# Download {{ project.name }} Client
git clone {{ repositories.base_url }}/{{ repositories.client }}.git
# Enter the cloned directory
cd client
# Install dependencies
pnpm install
```
To start the client for development, run
```bash
pnpm start
```
To build static files for the web (i.e. when hosting it yourself), run
```bash
pnpm build
```
Files will be built to `build`. These files need to be served by a Web Server such as Nginx or Apache, the `index.html` file cannot just be opened in a browser.
## Contributing
To contribute:
- [Fork the repository]({{ repositories.base_url }}/{{ repositories.client }}/fork)
- Run the building instructions.
- Commit & Push.
- Pull Request & Done!
### What can I 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]({{ repositories.base_url }}/{{ repositories.client }}/issues/21) is a good starting point and lists the core features that are still missing from the client.

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

@ -20,3 +20,4 @@ in the `{{ project.name.lower() }}-server` folder, with the format `NAME=VALUE`
| STORAGE_BUCKET | string | S3 bucket name | | STORAGE_BUCKET | string | S3 bucket name |
| STORAGE_REGION | string | S3 storage region | | STORAGE_REGION | string | S3 storage region |
| DB_LOGGING | boolean | if "true" logs all SQL queries to the terminal | | DB_LOGGING | boolean | if "true" logs all SQL queries to the terminal |
| LOG_REQUESTS | filter | What requests to log, per response code (eg. `-200` to log every non-200 response code, or `404` to log requests with a not found status code) |

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

@ -15,7 +15,7 @@ Below is a list of guild features that {{ project.name }} currently implements s
| `ALIASABLE_NAMES` | Allows multiple vanity URLs | | `ALIASABLE_NAMES` | Allows multiple vanity URLs |
| `VANITY_URL` | Allows vanity URLs | | `VANITY_URL` | Allows vanity URLs |
| `INTERNAL_EMPLOYEE_ONLY` | Requires all guild members be [staff](userFlags.md) | | `INTERNAL_EMPLOYEE_ONLY` | Requires all guild members be [staff](userFlags.md) |
| `INVITES_CLOSED` | Prevents joining this guild | | `INVITES_DISABLED` | Prevents joining this guild |
| `CROSS_CHANNEL_REPLIES` | Allows replies to be from outside the current channel | | `CROSS_CHANNEL_REPLIES` | Allows replies to be from outside the current channel |
| `ALLOW_INVALID_CHANNEL_NAMES` | Allow 'bad' channel names (spaces, invalid characters, etc) | | `ALLOW_INVALID_CHANNEL_NAMES` | Allow 'bad' channel names (spaces, invalid characters, etc) |
| `IRC_LIKE_CATEGORY_NAMES` | Use same validation for category names as channel names | | `IRC_LIKE_CATEGORY_NAMES` | Use same validation for category names as channel names |

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

@ -41,14 +41,14 @@ location /media/ {
``` ```
Along with any additional config you already have, of course. 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. Alternative (and perhaps the better choice) would be to create a new domain, say `media.example.com` specifically for Imagor.
??? "Example config for `media.whatever.com` site" ??? "Example config for `media.example.com` site"
```nginx ```nginx
server { server {
# Change the server_name to reflect your true domain # Change the server_name to reflect your true domain
server_name media.whatever.com; server_name media.example.com;
add_header Last-Modified $date_gmt; add_header Last-Modified $date_gmt;
proxy_set_header Host $host; proxy_set_header Host $host;

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

@ -1,12 +1,14 @@
# Configuration # Configuration
!!! info "Please see [this page](../database.md) for information regarding database configuration or where to access it."
!!! note "The `CONFIG_PATH` [environment variable](env.md) can be set to make {{ project.name }} use a JSON file instead of a database table."
{{ project.name }}'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. 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 For now, you can update this through SQL manually or a GUI database editor such as
[DBeaver](https://dbeaver.io/). [DBeaver](https://dbeaver.io/).
!!! 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 ## Array Types
Arrays are represented by \_[number] in a config key. For example, multiple `guild_defaultFeatures` may be assigned such as Arrays are represented by \_[number] in a config key. For example, multiple `guild_defaultFeatures` may be assigned such as
@ -86,7 +88,7 @@ Arrays are represented by \_[number] in a config key. For example, multiple `gui
| security_twoFactor_generateBackupCodes | true | boolean | Whether to generate backup codes for MFA users | | 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_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_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_forwardedFor](../reverseProxy.md) | null | string | HTTP header for user's real IP. |
| security_ipdataApiKey | {{ project.name }} 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_mfaBackupCodeCount | 10 | number | Number of MFA backup codes to generate |
| security_statsWorldReadable | true | boolean | Whether instance stats are publically accessible or require right | | security_statsWorldReadable | true | boolean | Whether instance stats are publically accessible or require right |

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

@ -1,12 +1,15 @@
# Database # Database
By default, {{ project.name }} 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 The SQLite database is stored in the `database.db` file at the server root by default.
You may delete this file to regenerate a new SQLite database on the next server start
(or through `npm run sync:db`).
However, 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. 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, We won't go into the setup of these servers here, given the scope of our documentation,
but to configure {{ project.name }} 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. to your new database connection string.
Usually, such a string will look something like Usually, such a string will look something like `type://username:password@your-IP/databaseName`
`type://username:password@your-IP/databaseName`

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

@ -67,17 +67,16 @@ They are simple HTML files, which you may edit freely. Although HTML mail is ver
Below are the available strings replaced in mail templates. Below are the available strings replaced in mail templates.
| string | replaced with | | string | replaced with |
| ------------------------ | ---------------------------------------------------------------------------- | | ----------------------- | ---------------------------------------------------------------------------- |
| `{instanceName}` | `general_instanceName` config value | | `{instanceName}` | `general_instanceName` config value |
| `{userUsername}` | The username of the user this email is being sent to | | `{userUsername}` | The username of the user this email is being sent to |
| `{userDiscriminator}` | The discriminator of the user this email is being sent to | | `{userDiscriminator}` | The discriminator of the user this email is being sent to |
| `{userId}` | The ID of the user this email is being sent to | | `{userId}` | The ID of the user this email is being sent to |
| `{phoneNumber}` | The last 4 digits of the user's phone number. | | `{phoneNumber}` | The last 4 digits of the user's phone number. |
| `{userEmail}` | The user's email address | | `{userEmail}` | The user's email address |
| `{emailVerificationUrl}` | The generated email verification URL | | `{actionUrl}` | The generated password reset or email verification link |
| `{passwordResetUrl}` | The generated password reset URL | | `{ipAddress}` | The IP address of new login (New login emails are not currently implemented) |
| `{ipAddress}` | The IP address of new login (New login emails are not currently implemented) | | `{locationCity}` | The GeoIP city of new login |
| `{locationCity}` | The GeoIP city of new login | | `{locationRegion}` | The GeoIP region of new login |
| `{locationRegion}` | The GeoIP region of new login | | `{locationCountryName}` | The GeoIP country of new login |
| `{locationCountryName}` | The GeoIP country of new login |

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

@ -14,8 +14,9 @@ We do not recommend using Windows to run {{ project.name }}.
## Dependencies ## Dependencies
- [Git](https://git-scm.com/) - [Git](https://git-scm.com/)
- [NodeJS](https://nodejs.org). Version 16+ - [NodeJS](https://nodejs.org). Version 18+ (for `npm`, `node` commands)
- [Python](https://www.python.org/). Version 3+. Make sure this is executable via `python` in your terminal. (NOTE: Ubuntu and Debian based systems often ship with an outdated version of NodeJS, so you can use [NodeSource](https://github.com/nodesource/distributions) to install a newer version)
- [Python](https://www.python.org/). Version 3.10 or later. Make sure this is executable via `python` in your terminal.
(See: `python-is-python3` package) (See: `python-is-python3` package)
- On Linux: `gcc`/`g++`. Packaged with `build-essential` on Debian/Ubuntu and `base-devel` on Arch. - 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. - On Windows: [Visual Studio](https://visualstudio.microsoft.com/) (**NOT** VSCode) with the `Desktop development with C++` package.
@ -30,7 +31,7 @@ In your terminal:
git clone {{ repositories.base_url }}/{{ repositories.server }}.git git clone {{ repositories.base_url }}/{{ repositories.server }}.git
# Navigate to project root # Navigate to project root
cd {{ project.name.lower() }}-server cd server
# Install javascript packages # Install javascript packages
npm i npm i

3
docs/setup/server/security/rights.md
View File

@ -1,7 +1,8 @@
## About ## About
Rights are instance-wide, per-user permissions for everything you may perform on the instance, 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. such as sending messages, editing messages, or shutting down the server. They are separate from
guild member permissions, which only apply to a given guild.
You may modify a users rights by editing the `rights` column in the `users` table. You may modify a users rights by editing the `rights` column in the `users` table.

25
docs/setup/server/wellknown.md Normal file
View File

@ -0,0 +1,25 @@
# well-known
Instance owners may host a `/.well-known/spacebar` file on a domain containing the instance's API endpoint for Spacebar instance discovery.
Users can enter a domain, e.g. `spacebar.chat` as shorthand, and their client will query `https://spacebar.chat/.well-known/spacebar` for the instance API URL,
and from there the Gateway and CDN endpoints.
For example:
=== "JSON"
```json
{
"api": "https://api.spacebar.chat/api/v9"
}
```
=== "NGINX"
```nginx
location /.well-known/spacebar {
add_header Access-Control-Allow-Origin *;
return 200 '{"api": "https://api.spacebar.chat/api/v9"}';
}
```

5
mkdocs.yml
View File

@ -25,10 +25,6 @@ plugins:
- section-index - section-index
- search - search
- macros - macros
- 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
@ -46,6 +42,7 @@ theme:
toggle: toggle:
icon: material/lightbulb icon: material/lightbulb
name: Switch to light mode name: Switch to light mode
custom_dir: docs/assets/overrides
features: features:
- navigation.expand - navigation.expand
- navigation.instant - navigation.instant

3
netlify.toml Normal file
View File

@ -0,0 +1,3 @@
[build]
publish = "dist"
command = "pip3 install -r requirements.txt && mkdocs build -d dist"

9
requirements.txt
View File

@ -1,5 +1,4 @@
mkdocs mkdocs==1.5.2
mkdocs-material mkdocs-material==9.1.21
mkdocs-swagger-ui-tag mkdocs-section-index==0.3.5
mkdocs-section-index mkdocs-macros-plugin==1.0.4
mkdocs-macros-plugin

1
runtime.txt Normal file
View File

@ -0,0 +1 @@
3.8