From a32c272ef7abdf0d27981774d5e20f8603df78aa Mon Sep 17 00:00:00 2001 From: MaddyUnderStars <46743919+MaddyUnderStars@users.noreply.github.com> Date: Mon, 20 Nov 2023 08:32:47 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20spacebar?= =?UTF-8?q?chat/docs@34561e6d5a80c507e8e6d0c6782d025c51db6196=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- search/search_index.json | 2 +- setup/server/index.html | 56 +++++++++++++++++++++++++++----- setup/server/systemd/index.html | 16 ++++----- sitemap.xml.gz | Bin 127 -> 127 bytes 4 files changed, 57 insertions(+), 17 deletions(-) diff --git a/search/search_index.json b/search/search_index.json index e99d90b..7ef8d96 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"

Interested in contributing? We'd love to have you on board! Click here

Want to skip to the server installation guide? Click here

Have a question? It might be in here

"},{"location":"#what-is-spacebar","title":"What is Spacebar?","text":"

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

Spacebar 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 Spacebar instance, which we believe will be immensely useful for any transition process between services.

As Spacebar is an entirely separate service from Discord.com, it means a Spacebar server by itself cannot access private data controlled by Discord.com. You cannot use a Spacebar server to chat with your friends on Discord.com. You also cannot use a Spacebar server to grant premium (\"Nitro\") features to a Discord.com account (although you can grant these to a Spacebar 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 Spacebar-aware clients that can be used to connect to multiple Spacebar-compatible instances with rich theming and plugin support.

"},{"location":"#support","title":"Support","text":"

For any kind of support regarding Spacebar, feel free to ask questions in our Discord.com server or our official Spacebar instance.

For bug reporting and feature requests please create an issue on Github.

"},{"location":"faq/","title":"Frequently Asked Questions","text":"Is Spacebar still in development? Production Ready?

Yes, Spacebar 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 Spacebar 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:

For a more complete overview of what is left unimplemented, please refer to the missing routes viewer

The Spacebar 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.

How do you use the Client?

As described in Clients, the official client is not ready yet. You are free to use a Spacebar compatible client to connect, but no support will be provided.

Voice/Video when?

Currently there is no voice or video support in any Spacebar 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.

Free Nitro?

Please do not use Discord trademarks to refer to anything regarding Spacebar. As an instance owner, you can grant yourself or others premium features which may be used to determine your abilities client-side. However, Spacebar-server currently does not have any distinction between premium and free users. All users can access all features, given they have the rights to do so.

You cannot give yourself premium features on Discord.com using a Spacebar instance.

How do I boost my guild? Or, how do I buy premium?

You cannot buy premium features through Spacebar, as Spacebar does not support any payment backend.

Additionally, Spacebar 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, Spacebar 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 you require. You can set them to be given to all guilds by default using the config guild_defaultFeatures array.

Can I log in with my Discord account?

No. Spacebar and Discord are entirely separate services, with their own separate databases and authentication. Spacebar 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.

Does Spacebar 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. Spacebar instances are hosted entirely by their owner(s).

If you mean Discord 'server' as in a guild, also no. Spacebar is not a proxy for Discord guilds. Spacebar 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 Spacebar 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. 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.

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 to ensure the Spacebar codebase is free of any proprietary code. We want absolutely nothing to do with it.

Is this illegal?

The Spacebar maintainers do not believe it to be, no. See: Oracle v. Google.

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. Spacebar 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.
Editing the database is annoying, is there a graphical interface for this?

Currently no, there is no graphical interface for managing your Spacebar instance. An admin dashboard is planned, but we currently have higher priorities right now.

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.

It's pretty funny how you have a Discord.com guild for support.

We know. Also that's not a question.

"},{"location":"contributing/","title":"Contributing","text":"

Have you read the Code of Conduct?

"},{"location":"contributing/#style-and-a-note-on-etiquette","title":"Style and a note on etiquette","text":""},{"location":"contributing/#structure","title":"Structure","text":"

Spacebar is written in Typescript and is comprised of 4 main parts:

"},{"location":"contributing/#implementing-endpoints-opcodes-etc","title":"Implementing endpoints, opcodes, etc","text":"

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.

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, here specifically.

Discord generally does not document anything that is not related to application/bot development, though. 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.

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. Easy fix though, just edit the DeveloperOptionsStore localStorage key so that logGatewayEvents is true, and reload the client.

Warning

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.

"},{"location":"contributing/conduct/","title":"Code of Conduct","text":"

By contributing to or interacting with Spacebar or Spacebar 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.

Spacebar community spaces includes Spacebar github repositories and Spacebar development guilds (be it on Discord.com or Spacebar instances mananged by the Spacebar maintainers group).

By contributing to any Spacebar projects (for example, through pull request) you guarantee that you have the rights to resign all rights to Spacebar under the AGPLV3 license.

"},{"location":"contributing/conduct/#desirable-behaviour","title":"Desirable Behaviour","text":""},{"location":"contributing/conduct/#prohibited-behaviour","title":"Prohibited Behaviour","text":"
  1. Sharing leaked, proprietary source code from Discord Inc
  2. Homophobia, transphobia, etc, misgendering, deadnaming, assuming gender. You should use singular they/them when in doubt.
  3. Threats of violence
  4. Harassment
  5. Spreading hateful, violent, or discriminatory ideologies or conspiracy theories, via media or text (including avatars and nicknames)
  6. Trolling. Intentionally derailing conversations or producing discussions on non-issues.
  7. Doxing. Disclosing other's private information without their consent.
  8. Spamming. This includes sending advertisements, repeatedly sending meaningless content, sending server invites unrequested.
  9. Sharing media that may cause harm or be triggering to others, such as flashing imagery or gore.
  10. Undesired automation of services that may lead to a reduction in service quality. For example, API spam of a Spacebar instance.
  11. Ban evasion. Creation of additional accounts used to join a community after being banned from that community.
  12. Posting content that is illegal to publish or distribute in Germany.
  13. Abusing loopholes in this code of conduct, or being in conflict with the goals of this code of conduct.
"},{"location":"contributing/conduct/#consequences-of-violation","title":"Consequences of Violation","text":""},{"location":"contributing/conduct/#reporting-problems","title":"Reporting problems","text":"

You may report any violation of this code of conduct to the Spacebar 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.

"},{"location":"contributing/conduct/#changes-to-this-document","title":"Changes to this document","text":"

This code of conduct may be changed in order to enhance clarity and precision at any time. Notification should be provided

"},{"location":"contributing/instances/","title":"For Instance Owners","text":"

The below are the rules for instance owners who look to be featured in our community instances list. If you do not meet these criteria, your instance will simply not be featured on our website.

Your instance:

  1. Rules must be in line with our Code of Conduct.
  2. Must not contain any Discord Inc. branding, such as including \"cord\" in the name or the Discord logo in promotional material.
  3. Must not host the Discord Inc. client in any capacity.
  4. Must be moderated for at least publically accessible guilds. This includes guilds accessible from Discovery or a 'guild directory' channel in an auto join guild.
  5. Must have at least regular uptime, meaning it is available at a consistent time of day.
  6. Must have a valid and monitored general_correspondenceEmail config set.
  7. Must not have default rights that include operator or other administrative rights.
  8. Enable 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:

"},{"location":"contributing/server/","title":"Contributing to spacebar-server","text":""},{"location":"contributing/server/#migrations","title":"Migrations","text":""},{"location":"contributing/server/#missing-routes","title":"Missing routes","text":""},{"location":"contributing/server/migrations/","title":"Migrations","text":""},{"location":"contributing/server/migrations/#what-you-need-to-know","title":"What you need to know","text":""},{"location":"contributing/server/migrations/#generating-migrations","title":"Generating Migrations","text":"

To generate a database migration in spacebar-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.
  2. Switch to branch/commit you want to migrate to, and run

    npm run generate:migration -- src/util/migrations/:dbms:/:migrationName:\n

    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. Obviously, this is not always what you want. Edit it to preserve as much of the original data as possible.

Once you've got your migration written, running the server will automatically run the migrations. Make sure you have backups of the original (step one) database, so you don't have to keep switching branches.

"},{"location":"contributing/server/missingroute/","title":"Missing Routes","text":"

Below is a list of routes available on Discord.com Spacebar-server does not currently implement.

It does not account for different HTTP methods (GET, POST, etc). A single method implemented by Spacebar will remove it from this list, so be sure to double check in the Spacebar source code.

It is generated daily by spacebarchat/missing-routes, by scraping the latest Discord.com client.

"},{"location":"setup/","title":"Setup","text":""},{"location":"setup/#server","title":"Server","text":""},{"location":"setup/#bots","title":"Bots","text":""},{"location":"setup/#clients","title":"Clients","text":""},{"location":"setup/bots/","title":"Bots and Applications","text":"

Spacebar 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 Spacebar instance instead.

The Discord Developer Panel is available at /developers, and allows you all the same functionality to create bots and applications on a Spacebar instance as Discord.com.

"},{"location":"setup/bots/#bot-libraries","title":"Bot Libraries","text":""},{"location":"setup/bots/#discordjs","title":"Discord.js","text":"

The Client class constructor accepts a http object, which you can use to change the endpoints used.

const { Client } = require(\"discord.js\");\n\nconst client = new Client({\nhttp: {\nversion: 9,\napi: \"https://api.spacebar.chat\",\ncdn: \"https://cdn.spacebar.chat\",\ninvite: \"https://spacebar.chat/invite\",\n},\n});\n\nclient.login(\"your token here\");\n
"},{"location":"setup/bots/#discordpy","title":"Discord.py","text":"
import discord\n\ndiscord.http.Route.BASE = \"https://api.spacebar.chat\"\nclient = discord.Client()\n\nclient.run('your token here')\n
"},{"location":"setup/bots/#jda","title":"JDA","text":"
import java.lang.reflect.*;\nimport net.dv8tion.jda.internal.requests.*;\n\npublic static void main(String[] args) {\nJDA jda = JDABuilder.createDefault(\"your token here\").build();\n\nField field = Requester.class.getDeclaredField(\"DISCORD_API_PREFIX\")\nfield.setAccessible(true);\n\nField modifiers = Field.class.getDeclaredField(\"modifiers\");\nmodifiers.setAccessible(true);\nmodifiers.setString(field, field.getModifiers() & ~Modifier.FINAL);\n\nfield.set(null, \"https://api.spacebar.chat\");\n}\n
"},{"location":"setup/clients/","title":"Clients","text":""},{"location":"setup/clients/#official-client","title":"Official Client","text":""},{"location":"setup/clients/official/","title":"Spacebar Client","text":"

The Spacebar client has 2 versions:

"},{"location":"setup/clients/official/legacy/","title":"Legacy Client","text":"

This version is no longer under active development! Please see React Client for the current in-development version.

Windows support is currently broken.

"},{"location":"setup/clients/official/legacy/#official-host","title":"Official host","text":"

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:

{\n\"api\": \"https://api.old.server.spacebar.chat/api/v9\",\n\"cdn\": \"https://cdn.old.server.spacebar.chat\",\n\"gateway\": \"wss://gateway.old.server.spacebar.chat\",\n\"invite\": \"https://old.server.spacebar.chat/invite\",\n\"template\": \"https://old.server.spacebar.chat/template\",\n\"gift\": \"https://old.server.spacebar.chat/gift\",\n\"scheduledEvent\": \"https://old.server.spacebar.chat/events\"\n}\n

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

"},{"location":"setup/clients/official/legacy/#setupbuilding","title":"Setup/Building","text":""},{"location":"setup/clients/official/legacy/#dependencies","title":"Dependencies","text":"

In your terminal:

# Download Spacebar Client\ngit clone https://github.com/spacebarchat/client.git -b legacy-v2\n\n# Enter the cloned directory\ncd client\n\n# Install dependencies\nyarn install\n

To start the client with Metro for development, run

yarn start\n

Platform-specific development commands:

For development for Android, run

yarn android\n

For development for iOS, run

yarn ios\n

For development for Windows, run

yarn windows\n

To build static files for the web (i.e. when hosting it yourself), run

yarn build:web\n

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.

"},{"location":"setup/clients/official/legacy/#contributing","title":"Contributing","text":"

This version is no longer being developed, you are free to clone the repository and make your own changes though!

"},{"location":"setup/clients/official/react/","title":"React Client","text":"

The Spacebar client is under heavy development and not ready to be used in production yet.

The official Spacebar client is currently being developed at this repository.

"},{"location":"setup/clients/official/react/#official-host","title":"Official host","text":"

The client is currently hosted at https://app.spacebar.chat. 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, 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.spacebar.chat, you'll need to make sure your instance allows CORS from that address.

"},{"location":"setup/clients/official/react/#setupbuilding","title":"Setup/Building","text":""},{"location":"setup/clients/official/react/#dependencies","title":"Dependencies","text":"

In your terminal:

# Download Spacebar Client\ngit clone https://github.com/spacebarchat/client.git\n\n# Enter the cloned directory\ncd client\n\n# Install dependencies\npnpm install\n

To start the client for development, run

pnpm start\n

To build static files for the web (i.e. when hosting it yourself), run

pnpm build\n

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.

"},{"location":"setup/clients/official/react/#contributing","title":"Contributing","text":"

To contribute:

"},{"location":"setup/clients/official/react/#what-can-i-contribute","title":"What can I contribute?","text":""},{"location":"setup/server/","title":"Server Setup","text":"

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

"},{"location":"setup/server/#dependencies","title":"Dependencies","text":""},{"location":"setup/server/#setup","title":"Setup","text":"

In your terminal:

# Download Spacebar\ngit clone https://github.com/spacebarchat/server.git\n\n# Navigate to project root\ncd server\n\n# Install javascript packages\nnpm i\n\n# Build and generate schema. Separately, they are `build` and `generate:schema`.\nnpm run setup\n\n# Start the bundle server ( API, CDN, Gateway in one )\nnpm run start\n

If all went according to plan, you can now access your new Spacebar instance at 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!).

"},{"location":"setup/server/#now-what","title":"Now what?","text":"

Well, now you can configure Spacebar to your liking!

"},{"location":"setup/server/database/","title":"Database","text":"

By default, Spacebar will use SQLite. SQLite is nice for testing or development. 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\u2122 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 Spacebar to use your shiny new database, simply set the DATABASE environment variable to your new database connection string.

Usually, such a string will look something like type://username:password@your-IP/databaseName

"},{"location":"setup/server/email/","title":"Email","text":"

Spacebar can be configured to send email, to enable the following functionality:

Spacebar supports the following email transports:

Once you have an account with one of the above services, or an SMTP service, you can begin configuring Spacebar to send mail.

You must edit:

Optionally:

"},{"location":"setup/server/email/#email-config","title":"Email Config","text":"SMTPMailgunMailjetSendgrid key type description email_smtp_host string SMTP Host for sending email email_smtp_port number SMTP port email_smtp_secure boolean Use TLS for SMTP email_smtp_username string SMTP username email_smtp_password string SMTP password key type description email_mailgun_apiKey string Mailgun API key email_mailgun_domain string Mailgun domain key type description email_mailjet_apiKey string Mailjet API key email_mailjet_apiSecret string Mailjet API secret key type description email_sendgrid_apiKey string Sendgrid API key"},{"location":"setup/server/email/#email-templates","title":"Email templates","text":"

Spacebar's email templates are stored in spacebar-server/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.

string replaced with {instanceName} general_instanceName config value {userUsername} The username 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 {phoneNumber} The last 4 digits of the user's phone number. {userEmail} The user's email address {actionUrl} The generated password reset or email verification link {ipAddress} The IP address of new login (New login emails are not currently implemented) {locationCity} The GeoIP city of new login {locationRegion} The GeoIP region of new login {locationCountryName} The GeoIP country of new login"},{"location":"setup/server/migatingFromStaging/","title":"Migrating from Staging","text":"

'Staging' refers to this branch of spacebar-server, which is deprecated in favour of the refactor branch (if this is a 404, its just become the main branch now).

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 spacebar-server git clone https://github.com/spacebarchat/server.git
  2. Copy your .env file from your previous installation to the new spacebar-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.

"},{"location":"setup/server/npmScripts/","title":"NPM scripts","text":"

Can be executed using npm run {script name}

"},{"location":"setup/server/npmScripts/#setup","title":"setup","text":"

Shorthand for build and generate:schema

"},{"location":"setup/server/npmScripts/#syncdb","title":"sync:db","text":"

Syncronise the database schema between Spacebar source code and your database. May incur data loss. You do not normally need to run this script, as Spacebar-server will perform it when necessary.

"},{"location":"setup/server/npmScripts/#build","title":"build","text":"

Builds the Spacebar source code

"},{"location":"setup/server/npmScripts/#start","title":"start","text":"

Starts the bundled server. API, Gateway, and CDN run under the same process when using bundle, using the same port.

"},{"location":"setup/server/npmScripts/#startapi-startgateway-startcdn","title":"start:api, start:gateway, start:cdn","text":"

Starts the respective component.

"},{"location":"setup/server/npmScripts/#generaterights","title":"generate:rights","text":"

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.

"},{"location":"setup/server/npmScripts/#generateschema","title":"generate:schema","text":"

Recreates the spacebar-server/assets/schema.json file, which is used for API and Gateway request validation.

"},{"location":"setup/server/reverseProxy/","title":"Reverse Proxy","text":""},{"location":"setup/server/reverseProxy/#nginx","title":"NGINX","text":"

Generally, our community sets up Spacebar 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/spacebar.conf file, and enable it with ln -s /etc/nginx/sites-available/spacebar.conf /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.

server {\n# Change server_name\nserver_name spacebar.example.com;\nlisten 80;\n\nlocation / {\n# Only change this if Nginx and Spacebar are not on the same machine.\nproxy_pass http://127.0.0.1:3001;\nproxy_set_header Host $host;\nproxy_pass_request_headers      on;\nadd_header Last-Modified $date_gmt;\nadd_header Cache-Control 'no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0';\nproxy_set_header  X-Real-IP $remote_addr;\nproxy_set_header  X-Forwarded-Proto https;\nproxy_set_header  X-Forwarded-For $remote_addr;\nproxy_set_header  X-Forwarded-Host $remote_addr;\nproxy_no_cache 1;\nproxy_cache_bypass 1;\n\n# This is important. It allows Websocket connections through NGINX.\nproxy_set_header Upgrade $http_upgrade;\nproxy_set_header Connection \"upgrade\";\n}\n\n# Uncomment this if using Imagor:\n#location /media/ {\n# # If you changed the port, be sure to change it here too\n# proxy_pass http://127.0.0.1:8000/;\n#}\n}\n
"},{"location":"setup/server/reverseProxy/#ssl","title":"SSL","text":"

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

UbuntuArchOther Distros
sudo apt install certbot python3-certbot-nginx\nsudo certbot --nginx\n
sudo pacman -Syu certbot certbot-nginx\nsudo certbot --nginx\n

Please refer to Certbots documentation

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 Spacebar 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).

"},{"location":"setup/server/systemd/","title":"SystemD","text":"

Below is an example SystemD service for running Spacebar. Save it in /etc/systemd/system/spacebar.service.

[Unit]\nDescription=Spacebar, for better and secure communication\n\n[Service]\nUser=<your user>\nWorkingDirectory=<spacebar directory>\nExecStart=npm run start\nRestart=always\nStandardError=journal\nStandardOutput=journal\n\n[Install]\nWantedBy=multi-user.target\n

Do not run Spacebar 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 Spacebar. 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. Also be sure to run RabbitMQ in that case.

You can now start Spacebar using sudo systemctl start spacebar.

To automatically run Spacebar on boot, use sudo systemctl enable spacebar.

To view the server logs, you may use journalctl -u spacebar, 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 spacebar | lnav

"},{"location":"setup/server/wellknown/","title":"well-known","text":"

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:

JSONNGINX
{\n\"api\": \"https://api.spacebar.chat/api/v9\"\n}\n
location /.well-known/spacebar {\nadd_header Access-Control-Allow-Origin *;\nreturn 200 '{\"api\": \"https://api.spacebar.chat/api/v9\"}';\n}\n
"},{"location":"setup/server/configuration/","title":"Configuration","text":"

Please see this page for information regarding database configuration or where to access it.

The CONFIG_PATH environment variable can be set to make Spacebar use a JSON file instead of a database table.

Spacebar'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.

"},{"location":"setup/server/configuration/#array-types","title":"Array Types","text":"

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"},{"location":"setup/server/configuration/#available-configuration-options","title":"Available Configuration Options","text":"key default type description 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_resizeHeightMax 1000 number Maximum image resize height for embeds. cdn_resizeWidthMax 1000 number Maximum image resize width for embeds. cdn_imagorServerUrl 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. api_endpointPublic \"/api\" string See gateway_endpointPublic general_instanceName Spacebar Instance string Announced instance name general_instanceDescription This is a Spacebar 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 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 usage security_jwtSecret Secure secret string The secret used for user token generation security_forwardedFor null string HTTP header for user's real IP. security_ipdataApiKey Spacebar 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 to expire login_requireCaptcha false boolean Whether login requires captcha verification login_requireVerification false boolean Whether login requires email 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 875069521787904 string The rights assigned to users upon registration regions_default spacebar 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 spacebar string[] The available voice region IDs regions_available_0_name Spacebar 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 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 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 true boolean Whether raw guild templates are allowed sentry_enabled false boolean Whether server-side Sentry analytics is enabled sentry_endpoint Spacebar 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 null string Twitter API key used for Twitter embeds email_provider null \"smtp\", \"mailgun\", \"mailjet\", \"sendgrid\" Which email transport to use email_smtp_host null string SMTP Host for sending email email_smtp_port null number SMTP port email_smtp_secure null boolean Use TLS for SMTP email_smtp_username null string SMTP username email_smtp_password null string SMTP password email_mailgun_apiKey null string Mailgun API key email_mailgun_domain null string Mailgun domain email_mailjet_apiKey null string Mailjet API key email_mailjet_apiSecret null string Mailjet API secret email_sendgrid_apiKey null string Sendgrid API key passwordReset_requireCaptcha false boolean Require captcha to send password reset email"},{"location":"setup/server/configuration/embeds/","title":"Embeds","text":"

Embeds in Spacebar are external content that is displayed within your messages when linked to. Spacebar 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 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.

"},{"location":"setup/server/configuration/embeds/#twitter","title":"Twitter","text":"

Go to the Twitter developer portal 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 value to your API key, wrapped in quotes.

"},{"location":"setup/server/configuration/env/","title":"Environment Variables","text":"

Below is a list of environment variables used by Spacebar. You can set environment variables easily by creating an .env file in the spacebar-server folder, with the format NAME=VALUE with each on new lines.

Name Value Description THREADS number Number of threads to run Spacebar 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 sent/received by gateway WS_DUMP boolean If set, dump websocket messages sent/received to disk 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 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)"},{"location":"setup/server/configuration/guildFeatures/","title":"Guild Features","text":"

Guild features are special modifiers assigned to guilds for additional functionality.

In Spacebar, 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 implemented on Discord.com is available here

Below is a list of guild features that Spacebar currently implements server-side, including ones not implemented by Discord.com:

Feature Description VIP_REGIONS Grants access to VIP voice regions ALIASABLE_NAMES Allows multiple vanity URLs VANITY_URL Allows vanity URLs INTERNAL_EMPLOYEE_ONLY Requires all guild members be staff INVITES_DISABLED Prevents joining this guild CROSS_CHANNEL_REPLIES Allows replies to be from outside the current channel 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 ALLOW_UNNAMED_CHANNELS Allow unnamed channels/categories DISCOVERABLE Show this guild in Discovery"},{"location":"setup/server/configuration/imagor/","title":"Imagor","text":"

Imagor is a \"fast, secure image processing server\" used by Spacebar for external image resizing, primarily by embeds from other websites when linked in a message. If left unused, Spacebar 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.

"},{"location":"setup/server/configuration/imagor/#dependencies","title":"Dependencies","text":""},{"location":"setup/server/configuration/imagor/#setup","title":"Setup","text":"

To setup Imagor for Spacebar, first grab the security_requestSignature config value from Spacebar'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 Spacebar config\nPORT=8000\n

You can now start Imagor with

docker run --env-file ./imagor.env -p 8000:8000 shumc/imagor\n

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 such as Nginx for Spacebar already, you could add this to your config's server block

location /media/ {\n# If you changed the port, be sure to change it here too\nproxy_pass http://127.0.0.1:8000/;\n}\n

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.example.com specifically for Imagor.

Example config for media.example.com site
server {\n# Change the server_name to reflect your true domain\nserver_name media.example.com;\n\nadd_header Last-Modified $date_gmt;\nproxy_set_header Host $host;\nproxy_pass_request_headers on;\nproxy_set_header X-Forwarded-For $remote_addr;\n\nlocation / {\n# If you had changed the port, change it here as well\nproxy_pass http://127.0.0.1:8000;\n}\n}\n

Our last step is to simply tell Spacebar 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.spacebar.chat/media\". If you used a subdomain, it will look like \"https://media.your.spacebar.chat\". Don't include a trailing backslash.

Congrats! After a restart, you've now got Imagor resizing your images!

"},{"location":"setup/server/configuration/rabbitmq/","title":"RabbitMQ","text":"

RabbitMQ is an open source message broker. Spacebar 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 Spacebar's config, 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 Spacebar over multiple systems, you'll need to set up access control in RabbitMQ.

"},{"location":"setup/server/configuration/userFlags/","title":"User Flags","text":"

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 implemented on Discord.com is available here

Currently, the only user flag to have an effect on server-side functionality is STAFF ( 1 ).

"},{"location":"setup/server/maintenance/","title":"Maintenance","text":""},{"location":"setup/server/maintenance/#when-do-i-have-to-restart-the-server","title":"When do I have to restart the server?","text":""},{"location":"setup/server/maintenance/#updating-spacebar-server","title":"Updating Spacebar-server","text":""},{"location":"setup/server/maintenance/restart/","title":"When must the server restart?","text":"

Spacebar-server must restart in the following cases:

For all other cases, you do not need to restart the server. For example:

This is not an exhaustive list. If a change you made is not applied, the first thing you should try is restarting.

"},{"location":"setup/server/maintenance/updating/","title":"Updating","text":"

If you had followed the setup guide, you'll have installed Spacebar using Git. Thus, you can update the server by running git pull in the spacebar-server directory.

If you had made any changes locally, you may run into merge conflicts, where the Spacebar 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:

# Install any new javascript packages\nnpm i\n\n# Build and generate schema\nnpm run setup\n\n# Start the server\nnpm run start\n
"},{"location":"setup/server/security/","title":"Security","text":"

There are various security measures available to instance owners.

"},{"location":"setup/server/security/#rights","title":"Rights","text":""},{"location":"setup/server/security/#captchas","title":"Captchas","text":""},{"location":"setup/server/security/#registration-tokens","title":"Registration Tokens","text":""},{"location":"setup/server/security/#rate-limits","title":"Rate Limits","text":""},{"location":"setup/server/security/captcha/","title":"CAPTCHAs","text":"

Spacebar currently supports two CAPTCHA providers; reCAPTCHA and hCaptcha.

hCaptchareCAPTCHA
  1. Navigate to https://www.hcaptcha.com/
  2. Create an account - Add hCaptcha for Publishers to my website or app
  3. Copy your sitekey to the config 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.
  1. Navigate to 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.spacebar.chat. Go to the next screen.
  5. Copy your sitekey to the config 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.

"},{"location":"setup/server/security/limits/","title":"Rate Limiting","text":"

Spacebar has various forms of rate limiting built in. If you are logged in, you can bypass these with the BYPASS_RATE_LIMITS right

"},{"location":"setup/server/security/limits/#absolute-ratelimiting","title":"Absolute ratelimiting","text":"

There are currently two types of absolute rate limiting:

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.

"},{"location":"setup/server/security/limits/#userip-specific-ratelimiting","title":"User/IP specific ratelimiting","text":"

These rate limits are enabled with a single toggle (limits_rate_enabled)

"},{"location":"setup/server/security/limits/#what-do-you-mean-by-window-and-count","title":"What do you mean by window and count?","text":"

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\nlimits_rate_ip_window = 1\n

will prevent all requests to any API endpoints from an IP if they exceed 10 requests in 1 second.

"},{"location":"setup/server/security/regTokens/","title":"Registration Tokens","text":"

Registration tokens are a one-time use token for allowing a new user registration to bypass various restrictions:

To create a registration token, send a GET request to /auth/generate-registration-tokens as an account with OPERATOR rights.

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.spacebar.chat/register?token=some token\n
"},{"location":"setup/server/security/rights/","title":"Rights","text":""},{"location":"setup/server/security/rights/#about","title":"About","text":"

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

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.

"},{"location":"setup/server/security/rights/#operator-rights","title":"OPERATOR Rights","text":"

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:

"},{"location":"setup/server/security/rights/#calculator","title":"Calculator","text":""},{"location":"setup/server/security/rights/#available-rights","title":"Available rights","text":"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 RESEND_VERIFICATION_EMAIL 1 << 49 Can resend verification emails (/auth/verify/resend)"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"

Interested in contributing? We'd love to have you on board! Click here

Want to skip to the server installation guide? Click here

Have a question? It might be in here

"},{"location":"#what-is-spacebar","title":"What is Spacebar?","text":"

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

Spacebar 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 Spacebar instance, which we believe will be immensely useful for any transition process between services.

As Spacebar is an entirely separate service from Discord.com, it means a Spacebar server by itself cannot access private data controlled by Discord.com. You cannot use a Spacebar server to chat with your friends on Discord.com. You also cannot use a Spacebar server to grant premium (\"Nitro\") features to a Discord.com account (although you can grant these to a Spacebar 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 Spacebar-aware clients that can be used to connect to multiple Spacebar-compatible instances with rich theming and plugin support.

"},{"location":"#support","title":"Support","text":"

For any kind of support regarding Spacebar, feel free to ask questions in our Discord.com server or our official Spacebar instance.

For bug reporting and feature requests please create an issue on Github.

"},{"location":"faq/","title":"Frequently Asked Questions","text":"Is Spacebar still in development? Production Ready?

Yes, Spacebar 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 Spacebar 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:

For a more complete overview of what is left unimplemented, please refer to the missing routes viewer

The Spacebar 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.

How do you use the Client?

As described in Clients, the official client is not ready yet. You are free to use a Spacebar compatible client to connect, but no support will be provided.

Voice/Video when?

Currently there is no voice or video support in any Spacebar 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.

Free Nitro?

Please do not use Discord trademarks to refer to anything regarding Spacebar. As an instance owner, you can grant yourself or others premium features which may be used to determine your abilities client-side. However, Spacebar-server currently does not have any distinction between premium and free users. All users can access all features, given they have the rights to do so.

You cannot give yourself premium features on Discord.com using a Spacebar instance.

How do I boost my guild? Or, how do I buy premium?

You cannot buy premium features through Spacebar, as Spacebar does not support any payment backend.

Additionally, Spacebar 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, Spacebar 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 you require. You can set them to be given to all guilds by default using the config guild_defaultFeatures array.

Can I log in with my Discord account?

No. Spacebar and Discord are entirely separate services, with their own separate databases and authentication. Spacebar 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.

Does Spacebar 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. Spacebar instances are hosted entirely by their owner(s).

If you mean Discord 'server' as in a guild, also no. Spacebar is not a proxy for Discord guilds. Spacebar 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 Spacebar 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. 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.

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 to ensure the Spacebar codebase is free of any proprietary code. We want absolutely nothing to do with it.

Is this illegal?

The Spacebar maintainers do not believe it to be, no. See: Oracle v. Google.

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. Spacebar 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.
Editing the database is annoying, is there a graphical interface for this?

Currently no, there is no graphical interface for managing your Spacebar instance. An admin dashboard is planned, but we currently have higher priorities right now.

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.

It's pretty funny how you have a Discord.com guild for support.

We know. Also that's not a question.

"},{"location":"contributing/","title":"Contributing","text":"

Have you read the Code of Conduct?

"},{"location":"contributing/#style-and-a-note-on-etiquette","title":"Style and a note on etiquette","text":""},{"location":"contributing/#structure","title":"Structure","text":"

Spacebar is written in Typescript and is comprised of 4 main parts:

"},{"location":"contributing/#implementing-endpoints-opcodes-etc","title":"Implementing endpoints, opcodes, etc","text":"

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.

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, here specifically.

Discord generally does not document anything that is not related to application/bot development, though. 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.

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. Easy fix though, just edit the DeveloperOptionsStore localStorage key so that logGatewayEvents is true, and reload the client.

Warning

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.

"},{"location":"contributing/conduct/","title":"Code of Conduct","text":"

By contributing to or interacting with Spacebar or Spacebar 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.

Spacebar community spaces includes Spacebar github repositories and Spacebar development guilds (be it on Discord.com or Spacebar instances mananged by the Spacebar maintainers group).

By contributing to any Spacebar projects (for example, through pull request) you guarantee that you have the rights to resign all rights to Spacebar under the AGPLV3 license.

"},{"location":"contributing/conduct/#desirable-behaviour","title":"Desirable Behaviour","text":""},{"location":"contributing/conduct/#prohibited-behaviour","title":"Prohibited Behaviour","text":"
  1. Sharing leaked, proprietary source code from Discord Inc
  2. Homophobia, transphobia, etc, misgendering, deadnaming, assuming gender. You should use singular they/them when in doubt.
  3. Threats of violence
  4. Harassment
  5. Spreading hateful, violent, or discriminatory ideologies or conspiracy theories, via media or text (including avatars and nicknames)
  6. Trolling. Intentionally derailing conversations or producing discussions on non-issues.
  7. Doxing. Disclosing other's private information without their consent.
  8. Spamming. This includes sending advertisements, repeatedly sending meaningless content, sending server invites unrequested.
  9. Sharing media that may cause harm or be triggering to others, such as flashing imagery or gore.
  10. Undesired automation of services that may lead to a reduction in service quality. For example, API spam of a Spacebar instance.
  11. Ban evasion. Creation of additional accounts used to join a community after being banned from that community.
  12. Posting content that is illegal to publish or distribute in Germany.
  13. Abusing loopholes in this code of conduct, or being in conflict with the goals of this code of conduct.
"},{"location":"contributing/conduct/#consequences-of-violation","title":"Consequences of Violation","text":""},{"location":"contributing/conduct/#reporting-problems","title":"Reporting problems","text":"

You may report any violation of this code of conduct to the Spacebar 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.

"},{"location":"contributing/conduct/#changes-to-this-document","title":"Changes to this document","text":"

This code of conduct may be changed in order to enhance clarity and precision at any time. Notification should be provided

"},{"location":"contributing/instances/","title":"For Instance Owners","text":"

The below are the rules for instance owners who look to be featured in our community instances list. If you do not meet these criteria, your instance will simply not be featured on our website.

Your instance:

  1. Rules must be in line with our Code of Conduct.
  2. Must not contain any Discord Inc. branding, such as including \"cord\" in the name or the Discord logo in promotional material.
  3. Must not host the Discord Inc. client in any capacity.
  4. Must be moderated for at least publically accessible guilds. This includes guilds accessible from Discovery or a 'guild directory' channel in an auto join guild.
  5. Must have at least regular uptime, meaning it is available at a consistent time of day.
  6. Must have a valid and monitored general_correspondenceEmail config set.
  7. Must not have default rights that include operator or other administrative rights.
  8. Enable 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:

"},{"location":"contributing/server/","title":"Contributing to spacebar-server","text":""},{"location":"contributing/server/#migrations","title":"Migrations","text":""},{"location":"contributing/server/#missing-routes","title":"Missing routes","text":""},{"location":"contributing/server/migrations/","title":"Migrations","text":""},{"location":"contributing/server/migrations/#what-you-need-to-know","title":"What you need to know","text":""},{"location":"contributing/server/migrations/#generating-migrations","title":"Generating Migrations","text":"

To generate a database migration in spacebar-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.
  2. Switch to branch/commit you want to migrate to, and run

    npm run generate:migration -- src/util/migrations/:dbms:/:migrationName:\n

    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. Obviously, this is not always what you want. Edit it to preserve as much of the original data as possible.

Once you've got your migration written, running the server will automatically run the migrations. Make sure you have backups of the original (step one) database, so you don't have to keep switching branches.

"},{"location":"contributing/server/missingroute/","title":"Missing Routes","text":"

Below is a list of routes available on Discord.com Spacebar-server does not currently implement.

It does not account for different HTTP methods (GET, POST, etc). A single method implemented by Spacebar will remove it from this list, so be sure to double check in the Spacebar source code.

It is generated daily by spacebarchat/missing-routes, by scraping the latest Discord.com client.

"},{"location":"setup/","title":"Setup","text":""},{"location":"setup/#server","title":"Server","text":""},{"location":"setup/#bots","title":"Bots","text":""},{"location":"setup/#clients","title":"Clients","text":""},{"location":"setup/bots/","title":"Bots and Applications","text":"

Spacebar 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 Spacebar instance instead.

The Discord Developer Panel is available at /developers, and allows you all the same functionality to create bots and applications on a Spacebar instance as Discord.com.

"},{"location":"setup/bots/#bot-libraries","title":"Bot Libraries","text":""},{"location":"setup/bots/#discordjs","title":"Discord.js","text":"

The Client class constructor accepts a http object, which you can use to change the endpoints used.

const { Client } = require(\"discord.js\");\n\nconst client = new Client({\nhttp: {\nversion: 9,\napi: \"https://api.spacebar.chat\",\ncdn: \"https://cdn.spacebar.chat\",\ninvite: \"https://spacebar.chat/invite\",\n},\n});\n\nclient.login(\"your token here\");\n
"},{"location":"setup/bots/#discordpy","title":"Discord.py","text":"
import discord\n\ndiscord.http.Route.BASE = \"https://api.spacebar.chat\"\nclient = discord.Client()\n\nclient.run('your token here')\n
"},{"location":"setup/bots/#jda","title":"JDA","text":"
import java.lang.reflect.*;\nimport net.dv8tion.jda.internal.requests.*;\n\npublic static void main(String[] args) {\nJDA jda = JDABuilder.createDefault(\"your token here\").build();\n\nField field = Requester.class.getDeclaredField(\"DISCORD_API_PREFIX\")\nfield.setAccessible(true);\n\nField modifiers = Field.class.getDeclaredField(\"modifiers\");\nmodifiers.setAccessible(true);\nmodifiers.setString(field, field.getModifiers() & ~Modifier.FINAL);\n\nfield.set(null, \"https://api.spacebar.chat\");\n}\n
"},{"location":"setup/clients/","title":"Clients","text":""},{"location":"setup/clients/#official-client","title":"Official Client","text":""},{"location":"setup/clients/official/","title":"Spacebar Client","text":"

The Spacebar client has 2 versions:

"},{"location":"setup/clients/official/legacy/","title":"Legacy Client","text":"

This version is no longer under active development! Please see React Client for the current in-development version.

Windows support is currently broken.

"},{"location":"setup/clients/official/legacy/#official-host","title":"Official host","text":"

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:

{\n\"api\": \"https://api.old.server.spacebar.chat/api/v9\",\n\"cdn\": \"https://cdn.old.server.spacebar.chat\",\n\"gateway\": \"wss://gateway.old.server.spacebar.chat\",\n\"invite\": \"https://old.server.spacebar.chat/invite\",\n\"template\": \"https://old.server.spacebar.chat/template\",\n\"gift\": \"https://old.server.spacebar.chat/gift\",\n\"scheduledEvent\": \"https://old.server.spacebar.chat/events\"\n}\n

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

"},{"location":"setup/clients/official/legacy/#setupbuilding","title":"Setup/Building","text":""},{"location":"setup/clients/official/legacy/#dependencies","title":"Dependencies","text":"

In your terminal:

# Download Spacebar Client\ngit clone https://github.com/spacebarchat/client.git -b legacy-v2\n\n# Enter the cloned directory\ncd client\n\n# Install dependencies\nyarn install\n

To start the client with Metro for development, run

yarn start\n

Platform-specific development commands:

For development for Android, run

yarn android\n

For development for iOS, run

yarn ios\n

For development for Windows, run

yarn windows\n

To build static files for the web (i.e. when hosting it yourself), run

yarn build:web\n

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.

"},{"location":"setup/clients/official/legacy/#contributing","title":"Contributing","text":"

This version is no longer being developed, you are free to clone the repository and make your own changes though!

"},{"location":"setup/clients/official/react/","title":"React Client","text":"

The Spacebar client is under heavy development and not ready to be used in production yet.

The official Spacebar client is currently being developed at this repository.

"},{"location":"setup/clients/official/react/#official-host","title":"Official host","text":"

The client is currently hosted at https://app.spacebar.chat. 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, 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.spacebar.chat, you'll need to make sure your instance allows CORS from that address.

"},{"location":"setup/clients/official/react/#setupbuilding","title":"Setup/Building","text":""},{"location":"setup/clients/official/react/#dependencies","title":"Dependencies","text":"

In your terminal:

# Download Spacebar Client\ngit clone https://github.com/spacebarchat/client.git\n\n# Enter the cloned directory\ncd client\n\n# Install dependencies\npnpm install\n

To start the client for development, run

pnpm start\n

To build static files for the web (i.e. when hosting it yourself), run

pnpm build\n

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.

"},{"location":"setup/clients/official/react/#contributing","title":"Contributing","text":"

To contribute:

"},{"location":"setup/clients/official/react/#what-can-i-contribute","title":"What can I contribute?","text":""},{"location":"setup/server/","title":"Server Setup","text":"

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

"},{"location":"setup/server/#dependencies","title":"Dependencies","text":""},{"location":"setup/server/#setup","title":"Setup","text":"

In your terminal:

# Download Spacebar\ngit clone https://github.com/spacebarchat/server.git\n\n# Navigate to project root\ncd server\n\n# Install javascript packages\nnpm i\n\n# Build and generate schema. Separately, they are `build` and `generate:schema`.\nnpm run setup\n\n# Start the bundle server ( API, CDN, Gateway in one )\nnpm run start\n

If all went according to plan, you can now access your new Spacebar instance at 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!).

"},{"location":"setup/server/#connecting-from-remote-machines","title":"Connecting from remote machines","text":"

For your server to be a bit more useful to those not on the same machine, you'll need to do a bit more configuration.

The official Spacebar client does automatic discovery of the endpoints it uses to communicate with the server, but it needs to retrieve those from somewhere, that being the API server.

If you don't tell the API server where to find the other services, the official Spacebar client wont be able to connect. Other clients which don't do automatic discovery will be, but that's because your users will need to provide the locations manually.

We'll be doing some server configuration in this step, which is stored in your servers database by default. By default, Spacebar uses an SQLite database in the project root called database.db, but you might not want to use that for production. If you're going to switch databases, do it now.

Once you've opened your database, navigate to the config table. You'll see 2 columns named key and value. You'll want to set the value of the rows with the following keys to the correct values.

key value api_publicEndpoint Your API endpoint. Likely \"https://DOMAIN_NAME/api/v9\" cdn_publicEndpoint Your CDN endpoint. Likely \"https://DOMAIN_NAME gateway_publicEndpoint Your Gateway endpoint. Likely \"wss://DOMAIN_NAME

You must wrap these values in doublequotes as they are parsed as JSON!

If you're in the CLI for this, heres some template SQL:

SQLite
update config\nset value = '\"HTTPS_OR_WSS://SERVER_ADDRESS\"'\nwhere key = \"THE_SERVICE_NAME_endpointPublic\";\n
"},{"location":"setup/server/#now-what","title":"Now what?","text":"

Well, now you can configure Spacebar to your liking!

"},{"location":"setup/server/database/","title":"Database","text":"

By default, Spacebar will use SQLite. SQLite is nice for testing or development. 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\u2122 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 Spacebar to use your shiny new database, simply set the DATABASE environment variable to your new database connection string.

Usually, such a string will look something like type://username:password@your-IP/databaseName

"},{"location":"setup/server/email/","title":"Email","text":"

Spacebar can be configured to send email, to enable the following functionality:

Spacebar supports the following email transports:

Once you have an account with one of the above services, or an SMTP service, you can begin configuring Spacebar to send mail.

You must edit:

Optionally:

"},{"location":"setup/server/email/#email-config","title":"Email Config","text":"SMTPMailgunMailjetSendgrid key type description email_smtp_host string SMTP Host for sending email email_smtp_port number SMTP port email_smtp_secure boolean Use TLS for SMTP email_smtp_username string SMTP username email_smtp_password string SMTP password key type description email_mailgun_apiKey string Mailgun API key email_mailgun_domain string Mailgun domain key type description email_mailjet_apiKey string Mailjet API key email_mailjet_apiSecret string Mailjet API secret key type description email_sendgrid_apiKey string Sendgrid API key"},{"location":"setup/server/email/#email-templates","title":"Email templates","text":"

Spacebar's email templates are stored in spacebar-server/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.

string replaced with {instanceName} general_instanceName config value {userUsername} The username 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 {phoneNumber} The last 4 digits of the user's phone number. {userEmail} The user's email address {actionUrl} The generated password reset or email verification link {ipAddress} The IP address of new login (New login emails are not currently implemented) {locationCity} The GeoIP city of new login {locationRegion} The GeoIP region of new login {locationCountryName} The GeoIP country of new login"},{"location":"setup/server/migatingFromStaging/","title":"Migrating from Staging","text":"

'Staging' refers to this branch of spacebar-server, which is deprecated in favour of the refactor branch (if this is a 404, its just become the main branch now).

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 spacebar-server git clone https://github.com/spacebarchat/server.git
  2. Copy your .env file from your previous installation to the new spacebar-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.

"},{"location":"setup/server/npmScripts/","title":"NPM scripts","text":"

Can be executed using npm run {script name}

"},{"location":"setup/server/npmScripts/#setup","title":"setup","text":"

Shorthand for build and generate:schema

"},{"location":"setup/server/npmScripts/#syncdb","title":"sync:db","text":"

Syncronise the database schema between Spacebar source code and your database. May incur data loss. You do not normally need to run this script, as Spacebar-server will perform it when necessary.

"},{"location":"setup/server/npmScripts/#build","title":"build","text":"

Builds the Spacebar source code

"},{"location":"setup/server/npmScripts/#start","title":"start","text":"

Starts the bundled server. API, Gateway, and CDN run under the same process when using bundle, using the same port.

"},{"location":"setup/server/npmScripts/#startapi-startgateway-startcdn","title":"start:api, start:gateway, start:cdn","text":"

Starts the respective component.

"},{"location":"setup/server/npmScripts/#generaterights","title":"generate:rights","text":"

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.

"},{"location":"setup/server/npmScripts/#generateschema","title":"generate:schema","text":"

Recreates the spacebar-server/assets/schema.json file, which is used for API and Gateway request validation.

"},{"location":"setup/server/reverseProxy/","title":"Reverse Proxy","text":""},{"location":"setup/server/reverseProxy/#nginx","title":"NGINX","text":"

Generally, our community sets up Spacebar 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/spacebar.conf file, and enable it with ln -s /etc/nginx/sites-available/spacebar.conf /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.

server {\n# Change server_name\nserver_name spacebar.example.com;\nlisten 80;\n\nlocation / {\n# Only change this if Nginx and Spacebar are not on the same machine.\nproxy_pass http://127.0.0.1:3001;\nproxy_set_header Host $host;\nproxy_pass_request_headers      on;\nadd_header Last-Modified $date_gmt;\nadd_header Cache-Control 'no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0';\nproxy_set_header  X-Real-IP $remote_addr;\nproxy_set_header  X-Forwarded-Proto https;\nproxy_set_header  X-Forwarded-For $remote_addr;\nproxy_set_header  X-Forwarded-Host $remote_addr;\nproxy_no_cache 1;\nproxy_cache_bypass 1;\n\n# This is important. It allows Websocket connections through NGINX.\nproxy_set_header Upgrade $http_upgrade;\nproxy_set_header Connection \"upgrade\";\n}\n\n# Uncomment this if using Imagor:\n#location /media/ {\n# # If you changed the port, be sure to change it here too\n# proxy_pass http://127.0.0.1:8000/;\n#}\n}\n
"},{"location":"setup/server/reverseProxy/#ssl","title":"SSL","text":"

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

UbuntuArchOther Distros
sudo apt install certbot python3-certbot-nginx\nsudo certbot --nginx\n
sudo pacman -Syu certbot certbot-nginx\nsudo certbot --nginx\n

Please refer to Certbots documentation

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 Spacebar 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).

"},{"location":"setup/server/systemd/","title":"SystemD","text":"

Below is an example SystemD service for running Spacebar. Save it in /etc/systemd/system/spacebar.service.

[Unit]\nDescription=Spacebar, for better and secure communication\n\n[Service]\nUser=<your user>\nWorkingDirectory=<spacebar directory>\nExecStart=npm run start\nRestart=always\nStandardError=journal\nStandardOutput=journal\n\n[Install]\nWantedBy=multi-user.target\n

Do not run Spacebar 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 Spacebar. 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. Also be sure to run RabbitMQ in that case.

You can now start Spacebar using sudo systemctl start spacebar.

To automatically run Spacebar on boot, use sudo systemctl enable spacebar.

To view the server logs, you may use journalctl -u spacebar, 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 spacebar | lnav

"},{"location":"setup/server/wellknown/","title":"well-known","text":"

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:

JSONNGINX
{\n\"api\": \"https://api.spacebar.chat/api/v9\"\n}\n
location /.well-known/spacebar {\nadd_header Access-Control-Allow-Origin *;\nreturn 200 '{\"api\": \"https://api.spacebar.chat/api/v9\"}';\n}\n
"},{"location":"setup/server/configuration/","title":"Configuration","text":"

Please see this page for information regarding database configuration or where to access it.

The CONFIG_PATH environment variable can be set to make Spacebar use a JSON file instead of a database table.

Spacebar'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.

"},{"location":"setup/server/configuration/#array-types","title":"Array Types","text":"

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"},{"location":"setup/server/configuration/#available-configuration-options","title":"Available Configuration Options","text":"key default type description 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_resizeHeightMax 1000 number Maximum image resize height for embeds. cdn_resizeWidthMax 1000 number Maximum image resize width for embeds. cdn_imagorServerUrl 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. api_endpointPublic \"/api\" string See gateway_endpointPublic general_instanceName Spacebar Instance string Announced instance name general_instanceDescription This is a Spacebar 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 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 usage security_jwtSecret Secure secret string The secret used for user token generation security_forwardedFor null string HTTP header for user's real IP. security_ipdataApiKey Spacebar 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 to expire login_requireCaptcha false boolean Whether login requires captcha verification login_requireVerification false boolean Whether login requires email 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 875069521787904 string The rights assigned to users upon registration regions_default spacebar 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 spacebar string[] The available voice region IDs regions_available_0_name Spacebar 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 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 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 true boolean Whether raw guild templates are allowed sentry_enabled false boolean Whether server-side Sentry analytics is enabled sentry_endpoint Spacebar 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 null string Twitter API key used for Twitter embeds email_provider null \"smtp\", \"mailgun\", \"mailjet\", \"sendgrid\" Which email transport to use email_smtp_host null string SMTP Host for sending email email_smtp_port null number SMTP port email_smtp_secure null boolean Use TLS for SMTP email_smtp_username null string SMTP username email_smtp_password null string SMTP password email_mailgun_apiKey null string Mailgun API key email_mailgun_domain null string Mailgun domain email_mailjet_apiKey null string Mailjet API key email_mailjet_apiSecret null string Mailjet API secret email_sendgrid_apiKey null string Sendgrid API key passwordReset_requireCaptcha false boolean Require captcha to send password reset email"},{"location":"setup/server/configuration/embeds/","title":"Embeds","text":"

Embeds in Spacebar are external content that is displayed within your messages when linked to. Spacebar 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 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.

"},{"location":"setup/server/configuration/embeds/#twitter","title":"Twitter","text":"

Go to the Twitter developer portal 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 value to your API key, wrapped in quotes.

"},{"location":"setup/server/configuration/env/","title":"Environment Variables","text":"

Below is a list of environment variables used by Spacebar. You can set environment variables easily by creating an .env file in the spacebar-server folder, with the format NAME=VALUE with each on new lines.

Name Value Description THREADS number Number of threads to run Spacebar 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 sent/received by gateway WS_DUMP boolean If set, dump websocket messages sent/received to disk 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 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)"},{"location":"setup/server/configuration/guildFeatures/","title":"Guild Features","text":"

Guild features are special modifiers assigned to guilds for additional functionality.

In Spacebar, 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 implemented on Discord.com is available here

Below is a list of guild features that Spacebar currently implements server-side, including ones not implemented by Discord.com:

Feature Description VIP_REGIONS Grants access to VIP voice regions ALIASABLE_NAMES Allows multiple vanity URLs VANITY_URL Allows vanity URLs INTERNAL_EMPLOYEE_ONLY Requires all guild members be staff INVITES_DISABLED Prevents joining this guild CROSS_CHANNEL_REPLIES Allows replies to be from outside the current channel 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 ALLOW_UNNAMED_CHANNELS Allow unnamed channels/categories DISCOVERABLE Show this guild in Discovery"},{"location":"setup/server/configuration/imagor/","title":"Imagor","text":"

Imagor is a \"fast, secure image processing server\" used by Spacebar for external image resizing, primarily by embeds from other websites when linked in a message. If left unused, Spacebar 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.

"},{"location":"setup/server/configuration/imagor/#dependencies","title":"Dependencies","text":""},{"location":"setup/server/configuration/imagor/#setup","title":"Setup","text":"

To setup Imagor for Spacebar, first grab the security_requestSignature config value from Spacebar'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 Spacebar config\nPORT=8000\n

You can now start Imagor with

docker run --env-file ./imagor.env -p 8000:8000 shumc/imagor\n

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 such as Nginx for Spacebar already, you could add this to your config's server block

location /media/ {\n# If you changed the port, be sure to change it here too\nproxy_pass http://127.0.0.1:8000/;\n}\n

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.example.com specifically for Imagor.

Example config for media.example.com site
server {\n# Change the server_name to reflect your true domain\nserver_name media.example.com;\n\nadd_header Last-Modified $date_gmt;\nproxy_set_header Host $host;\nproxy_pass_request_headers on;\nproxy_set_header X-Forwarded-For $remote_addr;\n\nlocation / {\n# If you had changed the port, change it here as well\nproxy_pass http://127.0.0.1:8000;\n}\n}\n

Our last step is to simply tell Spacebar 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.spacebar.chat/media\". If you used a subdomain, it will look like \"https://media.your.spacebar.chat\". Don't include a trailing backslash.

Congrats! After a restart, you've now got Imagor resizing your images!

"},{"location":"setup/server/configuration/rabbitmq/","title":"RabbitMQ","text":"

RabbitMQ is an open source message broker. Spacebar 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 Spacebar's config, 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 Spacebar over multiple systems, you'll need to set up access control in RabbitMQ.

"},{"location":"setup/server/configuration/userFlags/","title":"User Flags","text":"

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 implemented on Discord.com is available here

Currently, the only user flag to have an effect on server-side functionality is STAFF ( 1 ).

"},{"location":"setup/server/maintenance/","title":"Maintenance","text":""},{"location":"setup/server/maintenance/#when-do-i-have-to-restart-the-server","title":"When do I have to restart the server?","text":""},{"location":"setup/server/maintenance/#updating-spacebar-server","title":"Updating Spacebar-server","text":""},{"location":"setup/server/maintenance/restart/","title":"When must the server restart?","text":"

Spacebar-server must restart in the following cases:

For all other cases, you do not need to restart the server. For example:

This is not an exhaustive list. If a change you made is not applied, the first thing you should try is restarting.

"},{"location":"setup/server/maintenance/updating/","title":"Updating","text":"

If you had followed the setup guide, you'll have installed Spacebar using Git. Thus, you can update the server by running git pull in the spacebar-server directory.

If you had made any changes locally, you may run into merge conflicts, where the Spacebar 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:

# Install any new javascript packages\nnpm i\n\n# Build and generate schema\nnpm run setup\n\n# Start the server\nnpm run start\n
"},{"location":"setup/server/security/","title":"Security","text":"

There are various security measures available to instance owners.

"},{"location":"setup/server/security/#rights","title":"Rights","text":""},{"location":"setup/server/security/#captchas","title":"Captchas","text":""},{"location":"setup/server/security/#registration-tokens","title":"Registration Tokens","text":""},{"location":"setup/server/security/#rate-limits","title":"Rate Limits","text":""},{"location":"setup/server/security/captcha/","title":"CAPTCHAs","text":"

Spacebar currently supports two CAPTCHA providers; reCAPTCHA and hCaptcha.

hCaptchareCAPTCHA
  1. Navigate to https://www.hcaptcha.com/
  2. Create an account - Add hCaptcha for Publishers to my website or app
  3. Copy your sitekey to the config 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.
  1. Navigate to 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.spacebar.chat. Go to the next screen.
  5. Copy your sitekey to the config 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.

"},{"location":"setup/server/security/limits/","title":"Rate Limiting","text":"

Spacebar has various forms of rate limiting built in. If you are logged in, you can bypass these with the BYPASS_RATE_LIMITS right

"},{"location":"setup/server/security/limits/#absolute-ratelimiting","title":"Absolute ratelimiting","text":"

There are currently two types of absolute rate limiting:

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.

"},{"location":"setup/server/security/limits/#userip-specific-ratelimiting","title":"User/IP specific ratelimiting","text":"

These rate limits are enabled with a single toggle (limits_rate_enabled)

"},{"location":"setup/server/security/limits/#what-do-you-mean-by-window-and-count","title":"What do you mean by window and count?","text":"

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\nlimits_rate_ip_window = 1\n

will prevent all requests to any API endpoints from an IP if they exceed 10 requests in 1 second.

"},{"location":"setup/server/security/regTokens/","title":"Registration Tokens","text":"

Registration tokens are a one-time use token for allowing a new user registration to bypass various restrictions:

To create a registration token, send a GET request to /auth/generate-registration-tokens as an account with OPERATOR rights.

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.spacebar.chat/register?token=some token\n
"},{"location":"setup/server/security/rights/","title":"Rights","text":""},{"location":"setup/server/security/rights/#about","title":"About","text":"

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

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.

"},{"location":"setup/server/security/rights/#operator-rights","title":"OPERATOR Rights","text":"

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:

"},{"location":"setup/server/security/rights/#calculator","title":"Calculator","text":""},{"location":"setup/server/security/rights/#available-rights","title":"Available rights","text":"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 RESEND_VERIFICATION_EMAIL 1 << 49 Can resend verification emails (/auth/verify/resend)"}]} \ No newline at end of file diff --git a/setup/server/index.html b/setup/server/index.html index dcc7a64..3a96cc2 100644 --- a/setup/server/index.html +++ b/setup/server/index.html @@ -1167,13 +1167,6 @@ Setup - - -
  • - - Now what? - -
  • @@ -1231,8 +1224,55 @@

    Setup

    npm run start

    If all went according to plan, you can now access your new Spacebar instance at 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, +

    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!).

    +

    Connecting from remote machines

    +

    For your server to be a bit more useful to those not on the same machine, you'll need to do a bit more configuration.

    +

    The official Spacebar client does automatic discovery of the endpoints it uses to communicate with the server, +but it needs to retrieve those from somewhere, that being the API server.

    +

    If you don't tell the API server where to find the other services, the official Spacebar client wont be able to connect. +Other clients which don't do automatic discovery will be, but that's because your users will need to provide the locations manually.

    +

    We'll be doing some server configuration in this step, which is stored in your servers database by default. +By default, Spacebar uses an SQLite database in the project root called database.db, but you might not want to use that for production. +If you're going to switch databases, do it now.

    +

    Once you've opened your database, navigate to the config table. You'll see 2 columns named key and value. +You'll want to set the value of the rows with the following keys to the correct values.

    + + + + + + + + + + + + + + + + + + + + + +
    keyvalue
    api_publicEndpointYour API endpoint. Likely "https://DOMAIN_NAME/api/v9"
    cdn_publicEndpointYour CDN endpoint. Likely "https://DOMAIN_NAME
    gateway_publicEndpointYour Gateway endpoint. Likely "wss://DOMAIN_NAME
    +
    +

    You must wrap these values in doublequotes as they are parsed as JSON!

    +
    +

    If you're in the CLI for this, heres some template SQL:

    +
    +
    +
    +
    update config
    +set value = '"HTTPS_OR_WSS://SERVER_ADDRESS"'
    +where key = "THE_SERVICE_NAME_endpointPublic";
    +
    +
    +
    +

    Now what?

    Well, now you can configure Spacebar to your liking!