mirror of
https://github.com/movie-web/docs.git
synced 2025-09-13 14:53:26 +00:00
Initial draft
This commit is contained in:
qtchaos
@@ -1,22 +1,25 @@
|
||||
---
|
||||
title: 'Introduction'
|
||||
---
|
||||
|
||||
# Introduction to the backend
|
||||
|
||||
The backend is essentially just an account server. There is not much more to it.
|
||||
The backend is essentially just an account server, there is not much more to it. The client will work fine without it, but no syncing options will be available.
|
||||
|
||||
## Metrics
|
||||
|
||||
The backend exposes prometheus metrics, it can be accessed on `/metrics`.
|
||||
The backend exposes an endpoint for [Prometheus metrics](https://prometheus.io/){target="\_blank"} which allows you to keep track of the backend more easily, it can be accessed on `/metrics`.
|
||||
To view these metrics properly, you'll need to use an analytics program like [Grafana](https://grafana.com/){target="\_blank"}, [which can visualize logs from Prometheus](https://prometheus.io/docs/visualization/grafana/){target="\_blank"}.
|
||||
|
||||
## Security
|
||||
|
||||
Optionally, there are a few security settings:
|
||||
- Recaptcha support, the server can verify Recaptcha v3 tokens on register and login.
|
||||
- Ratelimits, Some expensive endpoints have ratelimits, but only when enabled. This requires an additional redis connection.
|
||||
|
||||
- [Recaptcha support](2.configuration.md#captcha), the server can verify Recaptcha v3 tokens on register and login.
|
||||
- [Ratelimits](2.configuration.md#ratelimits), some expensive endpoints have ratelimits, but only when enabled. This requires an additional redis connection.
|
||||
|
||||
## Migrations
|
||||
|
||||
To run migrations, You can use the command `pnpm migration:up` inside the docker container.
|
||||
Migrations help keep your database schema in sync with everyone else. To run migrations, you can use the `pnpm migration:up` command inside the docker container or in your command-line if you're not using docker.
|
||||
|
||||
Alternatively, you can enabled `postgres.migrateOnBoot` and it will be automatically migrated on boot.
|
||||
Alternatively, you can enable the [`postgres.migrateOnBoot`](2.configuration.md#postgresmigrateonboot) variable and it will be automatically migrated on boot.
|
||||
|
||||
@@ -1,27 +1,34 @@
|
||||
---
|
||||
title: 'Deploy'
|
||||
---
|
||||
|
||||
# Deploying the backend
|
||||
|
||||
The only officially recognized hosting method is through Docker (or similar container runtimes).
|
||||
|
||||
It can be scaled horizontally to all your heart's content.
|
||||
The only officially recognized hosting method is through Docker (or similar container runtimes). It can be scaled horizontally to all your heart's content and is the safest way to host the backend.
|
||||
|
||||
For configuration, check out the [configuration reference](2.configuration.md).
|
||||
|
||||
::alert{type="info"}
|
||||
The postgres database will need to be populated with [migrations](0.introduction.md) if `postgres.migrateOnBoot` isn't enabled.
|
||||
The postgres database will need to be populated with [migrations](0.introduction.md#migrations) if `postgres.migrateOnBoot` isn't enabled.
|
||||
::
|
||||
|
||||
## Method 1 - Docker
|
||||
|
||||
For other versions, [check out the package page](https://github.com/movie-web/backend/pkgs/container/backend).
|
||||
This method will help you set up the backend with the bare minimum configuration options. You'll most likely want to [add some more environment variables](2.configuration.md) to customize your experience more thoroughly.
|
||||
|
||||
The command below will not work unless customized by you, change the [`MWB_POSTGRES__CONNECTION`](2.configuration.md#postgresconnection) and [`MWB_CRYPTO__SESSION_SECRET`](2.configuration.md#cryptosessionsecret) to something valid for the backend to function.
|
||||
|
||||
If you're using a hosted postgres database like [Neon](https://neon.tech/){target="\_blank"}, you'll also want to enable SSL support for the backend using the [`postgres.ssl`](2.configuration.md#postgresssl) option.
|
||||
|
||||
For other versions of the image, [check out the package page](https://github.com/movie-web/backend/pkgs/container/backend){target="\_blank"}.
|
||||
|
||||
```sh
|
||||
docker run \
|
||||
-p 80:80 \
|
||||
-e POSTGRES__CONNECTION=postgresql://localhost:5432 \
|
||||
-e CRYPTO__SESSION_SECRET=add-your-own-secret \
|
||||
-e META__NAME=unofficial-movie-web \
|
||||
-e MWB_POSTGRES__CONNECTION=postgresql://localhost:5432 \
|
||||
-e MWB_CRYPTO__SESSION_SECRET=add-your-own-secret \
|
||||
-e MWB_META__NAME=unofficial-movie-web \
|
||||
ghcr.io/movie-web/backend:latest
|
||||
```
|
||||
|
||||
After running that command, your backend [_should_](../1.self-hosting/4.troubleshooting.md) now be available on `localhost:80`. if you want to be able to connect to the backend outside of your local network (for example sharing it with your friends), then you'll need set up to port forwarding.
|
||||
|
||||
@@ -1,139 +1,238 @@
|
||||
---
|
||||
title: 'Configuration'
|
||||
---
|
||||
|
||||
# Backend Config Reference
|
||||
|
||||
The config the backend can be provided in 3 ways.
|
||||
The backend can be configured in 3 different ways:
|
||||
|
||||
- Make a `config.json` file in the working directory of the application (root of repository)
|
||||
- Make a `.env` file in the working directory of the application (root of repository)
|
||||
- Add environment variables to your system (or container)
|
||||
|
||||
## Method 1 - `config.json`
|
||||
These different config options are all mutually inclusive, so you can use multiple at the same time if you want to.
|
||||
|
||||
::alert{type="warning"}
|
||||
With any of these configurations, you have to have atleast three variables set for the server to function:
|
||||
[`postgres.connection`](#postgresconnection), [`crypto.sessionSecret`](#cryptosessionsecret) and [`meta.name`](#metaname)
|
||||
::
|
||||
|
||||
### Method 1 - `config.json`
|
||||
|
||||
This method uses nesting, so the key `server.basePath` with the value of `"/backend"` will result in a file that looks like this:
|
||||
|
||||
This method uses nesting. So the key `server.basePath`. Will result in a json file like this:
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"basePath": "/backend",
|
||||
}
|
||||
"server": {
|
||||
"basePath": "/backend"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Method 2 - `.env`
|
||||
### Method 2 - `.env`
|
||||
|
||||
The environment variable names use double underscores as separators and `MWB_` as the prefix. So the key `server.basePath` will result in the .env file like this:
|
||||
|
||||
```sh
|
||||
MWB_SERVER__BASE_PATH=/backend
|
||||
```
|
||||
|
||||
## Method 3 - Environment
|
||||
### Method 3 - Environment
|
||||
|
||||
This method is identical to the `.env` method listed above, but you add the variables to the environment instead of writing it in a file.
|
||||
|
||||
# Reference
|
||||
|
||||
## Server
|
||||
|
||||
All configurations related to the HTTP server.
|
||||
|
||||
### `server.port`
|
||||
|
||||
- Type: `number`
|
||||
- Default: `8080`
|
||||
|
||||
Port number that the HTTP server listens on.
|
||||
|
||||
Example: `8080`
|
||||
|
||||
### `server.cors`
|
||||
|
||||
- Type: `string`
|
||||
- Default: `""`
|
||||
- Example: `"https://movie-web.app https://testing.movie-web.app"`
|
||||
|
||||
Space seperated list of allowed origins.
|
||||
|
||||
Example:
|
||||
```
|
||||
https://movie-web.app https://testing.movie-web.app
|
||||
```
|
||||
|
||||
### `server.allowAnySite`
|
||||
If this setting is set to true, it allows any origin to access the site.
|
||||
This overwrites the setting at `server.cors`.
|
||||
|
||||
Example: `false`
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
If set to true, it allows any origin to access the site. This overwrites the [`server.cors`](#servercors) setting.
|
||||
|
||||
### `server.trustProxy`
|
||||
Should the server trust reverse proxy headers? This is used to identify users for ratelimiting
|
||||
|
||||
Example: `false`
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
Controls whether the server should trust reverse proxy headers. This is used to identify users for ratelimiting.
|
||||
|
||||
### `server.trustCloudflare`
|
||||
Should the server trust cloudflare IP headers? This is used to identify users for ratelimiting
|
||||
|
||||
Example: `false`
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
Controls whether the server should trust Cloudflare IP headers. This is used to identify users for ratelimiting.
|
||||
|
||||
### `server.basePath`
|
||||
Prefix for which path is being listened on. Useful you're hosting on `example.com/backend` for example.
|
||||
If this is set, you shouldn't apply url rewriting before proxying.
|
||||
|
||||
Example: `/backend`
|
||||
- Type: `string`
|
||||
- Default: `"/"`
|
||||
|
||||
Prefix for which path is being listened on. Useful if you're hosting on `example.com/backend` for example.
|
||||
|
||||
::alert{type="info"}
|
||||
If this is set, you shouldn't apply URL rewriting before proxying.
|
||||
::
|
||||
|
||||
## Logging
|
||||
|
||||
All configurations related to how the HTTP server will log. This is not related to the [metrics](0.introduction.md#metrics) endpoint.
|
||||
|
||||
### `logging.format`
|
||||
Logging format, Should be either `pretty` or `json`.
|
||||
|
||||
Example: `pretty`
|
||||
- Type: `string` | `"pretty" | "json"`
|
||||
- Default: `"pretty"`
|
||||
|
||||
Logging format to use, should be either `pretty` or `json`, most users should probably use the default.
|
||||
|
||||
## Postgres
|
||||
|
||||
All configurations related to how postgres functions.
|
||||
|
||||
### `postgres.connection` ⚠
|
||||
|
||||
- Type: `string`
|
||||
- Example: `"postgresql://localhost:5432"`
|
||||
|
||||
### `postgres.connection` - REQUIRED
|
||||
Connection URL for postgres instance, should contain the database in the URL.
|
||||
|
||||
Example: `postgresql://localhost:5432`
|
||||
::alert{type="danger"}
|
||||
**Required. The backend will not start if this is not configured.**
|
||||
::
|
||||
|
||||
### `postgres.migrateOnBoot`
|
||||
Run all migrations that haven't ran yet on boot.
|
||||
|
||||
Example: `false`
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
::alert{type="warn"}
|
||||
Run all [migrations](0.introduction.md#migrations) that haven't ran yet on boot.
|
||||
|
||||
::alert{type="warning"}
|
||||
If you have multiple replicas running, this can cause a lot of issues. We recommend only using this if you run only one replica.
|
||||
::
|
||||
|
||||
### `postgres.debugLogging`
|
||||
Log all postgres queries in the console, this outputs sensitive data so DO NOT run it in production.
|
||||
|
||||
Example: `false`
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
### `crypto.sessionSecret` - REQUIRED
|
||||
The secret used to sign sessions. Must be at least 32 characters long.
|
||||
Log all postgres queries in the console. Useful for debugging issues with the database.
|
||||
|
||||
Example: `Make your own`
|
||||
::alert{type="warning"}
|
||||
This outputs sensitive, **DO NOT** run it in production.
|
||||
::
|
||||
|
||||
### `meta.name` - REQUIRED
|
||||
## Cryptography
|
||||
|
||||
All configurations related to cryptography.
|
||||
|
||||
### `crypto.sessionSecret` ⚠
|
||||
|
||||
- Type: `string`
|
||||
|
||||
The secret used to sign sessions. **Must be at least 32 characters long.**
|
||||
|
||||
::alert{type="danger"}
|
||||
**Required. The backend will not start if this is not configured.**
|
||||
::
|
||||
|
||||
## Meta
|
||||
|
||||
These options configure how the server will display itself to the frontend.
|
||||
|
||||
### `meta.name` ⚠
|
||||
|
||||
- Type: `string`
|
||||
- Example: `"Unofficial movie-web"`
|
||||
|
||||
The name of the backend instance, this will be displayed to users who try to create an account.
|
||||
|
||||
Example: `Unofficial movie-web`
|
||||
::alert{type="danger"}
|
||||
**Required. The backend will not start if this is not configured.**
|
||||
::
|
||||
|
||||
### `meta.description`
|
||||
|
||||
- Type: `string`
|
||||
- Default: `""`
|
||||
- Example: `"This is not an official instance of movie-web"`
|
||||
|
||||
The description of the backend instance, this will be displayed to users who try to create an account.
|
||||
|
||||
Example: `This is not an official instance of movie-web`
|
||||
## Captcha
|
||||
|
||||
All configurations related to adding captcha functionality. Captchas' help to protect your server from bot attacks.
|
||||
|
||||
### `captcha.enabled`
|
||||
|
||||
To protect your server from bot attacks, captcha's can be useful to enabled. If this is enabled, all other captcha related settings are required.
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
Example: `false`
|
||||
Enables [Recaptcha](https://www.google.com/recaptcha/about/) support for user registration and login. [You can follow this guide to create a Recaptcha key](https://cloud.google.com/recaptcha-enterprise/docs/create-key-website#create-key){target="\_blank"}.
|
||||
|
||||
::alert{type="warning"}
|
||||
If this is enabled, all other captcha related settings are required.
|
||||
::
|
||||
|
||||
### `captcha.secret`
|
||||
|
||||
Google Recaptcha secret key.
|
||||
- Type: `string`
|
||||
- Default: `""`
|
||||
- Example: `"sjgaJ@3djasFVx"`
|
||||
|
||||
Example: `sjgaJ@3djasFVx`
|
||||
[Google Recaptcha](https://www.google.com/recaptcha/about/) secret key.
|
||||
|
||||
### `captcha.clientKey`
|
||||
|
||||
Google Recaptcha site key.
|
||||
- Type: `string`
|
||||
- Default: `""`
|
||||
- Example: `"2jf853z5bc63bvDb2323FAda"`
|
||||
|
||||
Example: `2jf853z5bc63bvDb2323FAda`
|
||||
[Google Recaptcha](https://www.google.com/recaptcha/about/) site key.
|
||||
|
||||
## Ratelimits
|
||||
|
||||
All configuration options related to adding ratelimiting functionality. Helps to protect against bot attacks or spammy users.
|
||||
|
||||
::alert{type="info"}
|
||||
Make sure your IP headers are properly forwarded if you're using a reverse proxy. Also see [`server.trustProxy`](#servertrustproxy).
|
||||
::
|
||||
|
||||
### `ratelimits.enabled`
|
||||
|
||||
To protect bot attacks or spammy users, you can enabled ratelimits. Make sure your ip headers are properly forwarded if you're using a reverse proxy. Also see `server.trustProxy`. If this is enabled, all other ratelimit related settings are required.
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
Example: `false`
|
||||
Enables ratelimiting some more expensive endpoints.
|
||||
|
||||
::alert{type="warning"}
|
||||
If this is enabled, all other ratelimit related settings are required.
|
||||
::
|
||||
|
||||
### `ratelimits.redisUrl`
|
||||
|
||||
Redis connection URL for storing ratelimit data. Just uses plain redis without any modules.
|
||||
- Type: `string`
|
||||
- Default: `""`
|
||||
- Example: `"redis://localhost:6379"`
|
||||
|
||||
Example: `redis://localhost:6379`
|
||||
Redis connection URL for storing ratelimit data. You can use a plain redis instance for this, no modules are required.
|
||||
|
||||
@@ -12,7 +12,6 @@ For this update, you will need to run migrations.
|
||||
- Removed unused table
|
||||
- Optimized prometheus metrics, should make less indexes
|
||||
|
||||
|
||||
# Version 1.1.5
|
||||
|
||||
Initial version of the backend.
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
title: 'Backend'
|
||||
icon: mdi:server-network
|
||||
icon: mdi:database
|
||||
navigation.redirect: /backend/introduction
|
||||
|
||||
Reference in New Issue
Block a user