From a22c87a08259585bdf26311cef414ccbf7a5badd Mon Sep 17 00:00:00 2001 From: Vendicated Date: Sun, 23 Jun 2024 16:09:44 +0200 Subject: [PATCH] improve self hosting documentation --- .env.example | 31 ++++++++++++++++++++---- .gitignore | 1 + README.md | 66 +++++++++++++++++++++++++++++++--------------------- 3 files changed, 68 insertions(+), 30 deletions(-) diff --git a/.env.example b/.env.example index 0d25193..3c46de7 100644 --- a/.env.example +++ b/.env.example @@ -1,19 +1,42 @@ +# Port and host to bind the server to. If running in Docker, there's no point changing them. PORT=8080 HOST=0.0.0.0 +# The URI used for connecting to redis REDIS_URI=localhost:6379 -ROOT_REDIRECT= +# URL that the root of the API will redirect to. +# The site specified here HAS TO link to the source code (including your modificiations, if applicable), +# to comply with the AGPL-3.0 license terms. +# If your instance is public, you should also provide a Privacy Policy for your users. +ROOT_REDIRECT=https://github.com/Vencord/Vencloud + +# Your Discord application data +# 1. Create application at https://discord.com/developers/applications +# 2. Navigate to the OAuth2 tab +# 3. Under "Client information", you'll find the client id and secret. You'll have to press "Reset Secret" to get the secret +# 4. Under "Redirects", click "Add Redirect" and add your domain with `/v1/oauth/callback` appended to it DISCORD_CLIENT_ID= DISCORD_CLIENT_SECRET= -DISCORD_REDIRECT_URI= +DISCORD_REDIRECT_URI=https://example.com/v1/oauth/callback +# This is prepended to the user ID before hashing to generate the key used to store their api secret. +# Can be generated via `openssl rand -hex 64`. At least 32 bytes should be used PEPPER_SECRETS= +# This is prepended to the user ID before hashing to generate the key used to store their settings. +# Can be generated with `openssl rand -hex 64`. At least 32 bytes should be used PEPPER_SETTINGS= -SIZE_LIMIT=33554432 +# The maximum settings backup size in bytes. Default is 32MB. +SIZE_LIMIT=32000000 +# List of Discord user IDs allowed to use the service, separated by commas. +# If empty, all users are allowed ALLOWED_USERS= +# Whether to enable and expose analytics at /metrics PROMETHEUS=false -PROXY_HEADER= +# The header containing the connecting user's ip when running behind a reverse proxy, +# e.g. X-Forwarded-For or CF-Connecting-IP. Used for anti abuse purposes. +# If not using a reverse proxy, leave this empty +PROXY_HEADER=X-Forwarded-For diff --git a/.gitignore b/.gitignore index d735254..bbadea2 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ docker-compose.override.yml # binaries Backend Backend.exe +backend diff --git a/README.md b/README.md index bcf7cb5..dcae692 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,48 @@ -# Backend -Vencord API +# Vencloud -## Hosting -The API has a Docker Compose configuration, so software-wise you shouldn't need much more than just Docker. -Docker is the official way of hosting the backend, and other setups (whilst technically supported) will be -up to you to manage. +Vencloud is Vencord's API for cloud settings sync! -1. Clone the repository -2. Copy `.env.example` to `.env` -3. Configure as necessary - - Port and host are irrelevant since it's running in a container, but you can change them if you wish. - - `REDIS_URI` should be changed to `redis:6379`. - - `ROOT_REDIRECT` should be changed to whatever you want the `/` of the API to be set to a different site, - like your own personal homepage. - - `DISCORD_*` should be configured with your Discord application. The redirect URI is `https:///v1/oauth/callback`. - - `PEPPER_*` should be unique values. These provide extra anonymity and make it more difficult to get user - info. It [is recommended](https://stackoverflow.com/a/9622855) you use at least 32 bytes of randomness, e.g. through - `openssl rand -hex 32`. - - `SIZE_LIMIT` is up to you, but should usually be left as default. This is for the settings sync and how - much data a user can store. - - `ALLOWED_USERS` restricts what users can use this API instance for operations like settings sync. - - `PROMETHEUS` controls whether or not to expose the `/metrics` endpoint. - - `PROXY_HEADER` should be used if you're running it behind a reverse proxy or another service (i.e., Cloudflare). -4. Create a `docker-compose.override.yml` that maps your ports, like so: +## Self Hosting + +> [!WARNING] +> Your instance has to be HTTPS capable due to [mixed content restrictions](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content) in web browsers. + +We provide a Docker build, so you don't need anything installed besides Docker! + +### Cloning the Repository + +First of all, you'll have to clone the source code to a convenient location: +```sh +git clone https://github.com/Vencord/Vencloud +``` + +### Setting up the Config + +Copy the example configuration (`.env.example`) to `.env`. Now open it with your text editor of trust and fill in the configuration values. +All variables are documented there! + +### Running + +Don't forget to direct your terminal to the Vencloud directory, e.g. via `cd Vencloud`! + +#### Via Docker + +1. Create a `docker-compose.override.yml` that maps the port from docker to your system. + The following example assumes you will use port `8485` ```yaml services: backend: ports: - - HOST_PORT:8080 + - 8485:8080 ``` -5. `docker compose up -d` +2. Start the docker container via `docker compose up -d`. The server will be available at the configured host, in the above example `8485` -Please note that, due to mixed content requirements, you will need HTTPS on your self-hosted instance. +#### Natively + +> [!WARNING] +> At the current moment, Go 21 is not yet supported, you'll need Go 20! +> An easy way to get Go 20 is to run `go install golang.org/dl/go1.20.0@latest` and then use the `go1.20` command instead of `go` + +1. Install the [Go programming language](https://go.dev/dl/) +2. Build the code: `go build -o backend` +3. Start the server: `./backend`