movie-web/docs
1
0
Fork 0
mirror of https://github.com/movie-web/docs.git synced 2025-09-13 05:03:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Write a lot, like an actual lot. of documentation

Browse Source 
Co-authored-by: William Oldham <github@binaryoverload.co.uk>
This commit is contained in:
mrjvs
2023-12-12 21:44:28 +01:00
parent c4d1622922
commit 042023dd11
21 changed files with 304 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
content/1.self-hosting/1.hosting-intro.md
View File

@@ -10,24 +10,24 @@ We **do not** provide support on how to self-host. If you can't figure it out th
There are a few configurations of hosting movie-web. Each with their own benefits.
**If you don't know what to choose, go with method 1.**
## Method 1 - only host the frontend
## Method 1 - Only host the frontend
With this method, you only host the essential parts that make movie-web work. But keep using the account server from offical movie-web.
This method is the easiest to self-host and is recommended for most users.
1. [Setup the Proxy!](2.proxy.md)
2. [Setup the Client!](3.client.md)
1. [Setup the Proxy!](../2.proxy/1.deploy.md)
2. [Setup the Client!](../3.client/1.deploy.md)
## Method 2 - only host the account server
## Method 2 - Only host the account server
If you want to own your own data, it's possible to selfhost just the account server and nothing else.
This method is only recommended if you have experience hosting databases or other similar stateful applications.
1. [Setup the Backend!](4.backend.md)
2. [Configure the Client!](5.use-backend.md)
1. [Setup the Backend!](../4.backend/1.deploy.md)
2. [Configure the Client!](../3.client/1.deploy.md)
## Method 3 - host everything
## Method 3 - Host everything
If you want an instance that's completely isolated from official movie-web. You can selfhost all parts.
This method is not recommended for inexperienced hosters.
1. [Setup the Proxy!](2.proxy.md)
2. [Setup the Backend!](4.backend.md)
3. [Setup the Client!](3.client.md)
1. [Setup the Proxy!](../2.proxy/1.deploy.md)
2. [Setup the Backend!](../4.backend/1.deploy.md)
3. [Setup the Client!](../3.client/1.deploy.md)

40
content/1.self-hosting/2.proxy.md
View File

@@ -1,40 +0,0 @@
---
title: 'The proxy'
---
# Setting up the proxy
Our proxy is used to bypass CORS-protected URLs on the client side, allowing users to make requests to protected endpoints without a backend server.
The proxy is made using [Nitro by UnJS](https://nitro.unjs.io/) which supports building the proxy to work on multiple providers including Cloudflare Workers, AWS Lambda and [more...](https://nitro.unjs.io/deploy)
Our recommended provider is Cloudflare due to its [generous free plan](https://www.cloudflare.com/en-gb/plans/developer-platform/).
## Cloudflare Workers
The proxy is made as a Cloudflare worker. Cloudflare has a generous free plan, so you don't need to pay anything unless you get hundreds of users.
[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/movie-web/simple-proxy)
1. Create a GitHub account at https://github.com if you don't have one.
1. Click the "Deploy with workers" button above.
1. Click the "Authorize Workers" button to authorise Cloudflare to talk to GitHub.
1. Authorize Cloudflare Workers in the GitHub page that pops up.
1. Follow the instructions to configure your Cloudflare account. Select "I have an account" if you have a Cloudflare account already, otherwise follow the link to create one.
1. Click the link to "Workers Dashboard" to find your account ID.
1. If you have used workers in the past, there will be a place on the right hand side to copy your account ID.
1. If you haven't used workers before, you can copy your account ID from the URL e.g. https://dash.cloudflare.com/ab7cb454c93987b6343350d4e84c16c7/workers-and-pages/create where `ab7cb454c93987b6343350d4e84c16c7` is the account ID.
1. Paste the account ID into the text box on the original Cloudflare workers page.
1. Click the link to "My Profile" to create an API token.
1. Click "Create Token".
1. Select "Use template" next to "Edit Cloudflare Workers".
1. Under "Account Resources", select "Include" and your account under the dropdown.
1. Under "Zone Resources", select "All zones" (You can select a more specific zone if you have the zones available).
1. At the bottom of the page, click "Continue to summary".
1. On the next screen, click "Create token".
1. Copy the API token and **save it in a safe place, it won't be shown again**.
1. Paste the API token into the Cloudflare Workers API Token text box.
1. Click "Fork the Repository" and follow the instructions to enable workflows.
1. Click "Deploy" to deploy to Cloudflare Workers.
1. Congratulations! Your worker is now deploying. Please wait for the GitHub Action to build and publish your worker.
1. You can click the "Worker dash" and "GitHub repo" buttons to see the status of the deploy.
1. When the worker has deployed, you will need to take note of the URL. This can be found on Cloudflare under Workers and Pages -> Overview -> proxy.

2
content/1.self-hosting/5.use-backend.md → content/1.self-hosting/2.use-backend.md
View File

@@ -3,4 +3,4 @@ title: 'Configure backend'
---
# Configure your client with the backend
// EXPLAIN HOW TO SET BACKEND URL ON OFFICIAL INSTANCE
// CONFIGURE IT HERE

0
content/1.self-hosting/6.about-pwa.md → content/1.self-hosting/3.about-pwa.md
View File

54
content/1.self-hosting/3.client.md
View File

@@ -1,54 +0,0 @@
---
title: 'The client'
---
# Setting up the client
## Method 1 - Vercel - Recommended
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmovie-web%2Fmovie-web%2Ftree%2Fmaster&env=VITE_CORS_PROXY_URL,VITE_TMDB_READ_API_KEY)
1. Click the Deploy button.
1. Sign in using either a GitHub, GitLab, or Bitbucket.
1. Follow the instructions to create a repository for movie-web.
1. Configure the environment variables:
- `VITE_CORS_PROXY_URL`: Enter your proxy URL here. Make sure to not have a slash at the end of your URL.
Example (THIS IS AN EXAMPLE, IT WON'T WORK FOR YOU): `https://test-proxy.test.workers.dev`
- `VITE_TMDB_READ_API_KEY`: Enter your TMDB Read Access Token here. Please read [below](#tmdb-api-key) on how to get an API key.
- `VITE_BACKEND_URL`: Only set if you have a selfhosted backend. Put in your backend URL. Check out [configuration reference](../4.client/2.configuration.md) for details. Make sure to not have a slash at the end of the URL.
1. Click "Deploy"
1. Congrats! You have your own version of movie-web hosted.
1. You may wish to configure a custom domain - Please consult [the Vercel docs for how to do this](https://vercel.com/docs/getting-started-with-vercel/domains).
## Method 2 - Any Static Web Host
1. Download the file `movie-web.zip` from the latest release: https://github.com/movie-web/movie-web/releases/latest.
2. Extract the ZIP file so you can edit the files.
3. Open `config.js` in an editor such as Notepad, Visual Studio Code or similar.
4. Put your proxy URL in-between the double quotes of `VITE_CORS_PROXY_URL: ""`. Make sure to not have a slash at the end of your URL.
Example (THIS IS AN EXAMPLE, IT WON'T WORK FOR YOU): `VITE_CORS_PROXY_URL: "https://test-proxy.test.workers.dev"`
5. Put your TMDB Read Access Token inside the quotes of `VITE_TMDB_READ_API_KEY: ""`. Please read [below](#tmdb-api-key) on how to get an API key.
6. Save the file.
7. Upload **all** of the files to a static website hosting such as:
- GitHub Pages
- Netlify
- Vercel
- Etc, there are lots - Google it if the ones above don't work for you.
1. Congrats! You have your own version of movie-web hosted.
## TMDB API Key
In order to search for movies and TV shows, we use an API called "The Movie Database" (TMDB). In order for your client to be able to search, you need to generate an API key.
::alert{type="info"}
The API key is **free**, you just need to create an account.
::
1. Create an account at https://www.themoviedb.org/signup
1. You will be required to verify your email; click the link that you get sent to verify your account.
1. Go to https://www.themoviedb.org/settings/api/request to create a developer account.
1. Read the terms and conditions and accept them.
1. Fill out your details:
- Select "Website" as type of use.
- For the other details can put any values; they are not important.
1. Copy the "API Read Access Token" - **DO NOT COPY THE API Key - IT WILL NOT WORK**

6
content/1.self-hosting/4.backend.md
View File

@@ -1,6 +0,0 @@
---
title: 'The backend'
---
# Setting up the backend
// EXPLAIN HOW TO HOST THE BACKEND

0
content/1.self-hosting/7.troubleshooting.md → content/1.self-hosting/4.troubleshooting.md
View File

5
content/2.proxy/0.introduction.md
View File

@@ -2,5 +2,8 @@
title: 'Introduction'
---
# Introduction to the proxy
Our proxy is used to bypass CORS-protected URLs on the client side, allowing users to make requests to CORS protected endpoints without a backend server.
// EXPLAIN WHAT A PROXY IS
The proxy is made using [Nitro by UnJS](https://nitro.unjs.io/) which supports building the proxy to work on multiple providers including Cloudflare Workers, AWS Lambda and [more...](https://nitro.unjs.io/deploy)
Our recommended provider is Cloudflare due to its [generous free plan](https://www.cloudflare.com/en-gb/plans/developer-platform/).

60
content/2.proxy/1.deploy.md
View File

@@ -3,16 +3,62 @@ title: 'Deploy'
---
# Deploying the proxy
// FILL PAGE
## Method 1 - Cloudflare (Easy)
## Method 1 - cloudflare (easy)
Cloudflare has a generous free plan, so you don't need to pay anything unless you get hundreds of users.
// EXPLAIN HOW TO DEPLOY TO CLOUDFLARE with button
[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/movie-web/simple-proxy)
## Method 1 - cloudflare (manual)
1. Create a GitHub account at https://github.com if you don't have one.
1. Click the `Deploy with workers` button above.
1. Click the `Authorize Workers` button to authorise Cloudflare to talk to GitHub.
1. Authorize Cloudflare Workers in the GitHub page that pops up.
1. Follow the instructions to configure your Cloudflare account. Select `I have an account` if you have a Cloudflare account already, otherwise follow the link to create one.
1. Click the link to `Workers Dashboard` to find your account ID.
1. You can copy your account ID from the URL e.g. https://dash.cloudflare.com/ab7cb454c93987b6343350d4e84c16c7/workers-and-pages/create where `ab7cb454c93987b6343350d4e84c16c7` is the account ID.
1. Paste the account ID into the text box on the original Cloudflare workers page.
1. Click the link to `My Profile` to create an API token.
1. Click `Create Token`.
1. Select `Use template` next to `Edit Cloudflare Workers`.
1. Under `Account Resources`, select `Include` and your account under the dropdown.
1. Under `Zone Resources`, select `All zones` (You can select a more specific zone if you have the zones available).
1. At the bottom of the page, click `Continue to summary`.
1. On the next screen, click `Create token`.
1. Copy the API token and **save it in a safe place, it won't be shown again**.
1. Paste the API token into the Cloudflare Workers API Token text box.
1. Click `Fork the Repository` and follow the instructions to enable workflows.
1. Click `Deploy` to deploy to Cloudflare Workers.
1. Congratulations! Your worker is now deploying. Please wait for the GitHub Action to build and publish your worker.
1. You can click the `Worker dash` and `GitHub repo` buttons to see the status of the deploy.
1. When the worker has deployed, you will need to take note of the URL. This can be found on Cloudflare under Workers and Pages -> Overview -> Proxy.
// EXPLAIN HOW TO DEPLOY TO CLOUDFLARE MANUALLY
## Method 1 - Cloudflare (Manual)
1. Login to your Cloudflare account if you have one, otherwise create one [here](https://dash.cloudflare.com/sign-up)
1. If you are signing up for an account, make sure to verify your email before going further!
1. Download the latest version of the Cloudflare [`simple-proxy-cloudflare.mjs` script from here](https://github.com/movie-web/simple-proxy/releases/latest/download/simple-proxy-cloudflare.mjs).
1. Go to `Workers & Pages` and then `Overview` in the left-hand navigation bar.
1. Click the `Create Worker` button
1. If you've made a worker or pages application before, you will need to click `Create Application` first
1. Give your worker a name and click `Deploy`. This can be anything you would like!
1. On the `Congratulations` web page, click the `Edit code` button to edit the code in the worker you have just created.
1. There should now be a code editor on the left hand side on the web page.
1. Select all of the existing template code and delete it. **You must make sure all of the code is deleted for this to work!**
1. Go to your downloads folder and open up the `simple-proxy-cloudflare.mjs` file you downloaded earlier in a text editor, and **copy** the contents.
1. Back in your browser, paste the contents of the file into the code editor.
1. The `Save and deploy` button in the top right corner should now be active, click it to deploy your proxy!
1. A confirmation dialog will appear, click `Save and deploy` once more.
1. Your worker is now deployed! You can click the back button in the top left to take you back to the summary screen.
1. On the summary screen, your worker link will be displayed under `Preview`. Right click the link, click `Copy link address` and save the link somewhere - you will need it to setup the client!
## Method 2 - docker
## Method 2 - Docker
// EXPLAIN HOW TO DEPLOY WITH DOCKER
::alert{type="warning"}
Experience with Docker, domains and web hosting is **highly recommended** for this method. <br />
[Deploying with Cloudflare](#method-1-cloudflare-easy) is easier and safer to do! You are exposing your server at your own risk!
::
Our `simple-proxy` application is available from the GitHub Container Registry under the image `ghcr.io/movie-web/simple-proxy:latest` :copy-button{content="ghcr.io/movie-web/simple-proxy:latest"}
The container exposes the HTTP port (Without TLS/SSL) as `3000/TCP`.
If you know what you are doing, you should know what to do with this information. If you don't, then please follow our Cloudflare guides.

35
content/3.client/1.deploy.md
View File

@@ -3,12 +3,35 @@ title: 'Deploy'
---
# Deploying the client
// FILL PAGE
## Method 1 - Vercel - Recommended
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmovie-web%2Fmovie-web%2Ftree%2Fmaster&env=VITE_CORS_PROXY_URL,VITE_TMDB_READ_API_KEY)
1. Click the Deploy button.
1. Sign in using either a GitHub, GitLab, or Bitbucket.
1. Follow the instructions to create a repository for movie-web.
1. Configure the environment variables:
- `VITE_CORS_PROXY_URL`: Enter your proxy URL here. Make sure to not have a slash at the end of your URL.
Example (THIS IS AN EXAMPLE, IT WON'T WORK FOR YOU): `https://test-proxy.test.workers.dev`
- `VITE_TMDB_READ_API_KEY`: Enter your TMDB Read Access Token here. Please read [the TMDB page](2.tmdb.md) on how to get an API key.
## Method 1 - vercel
- `VITE_BACKEND_URL`: Only set if you have a self-hosted backend. Put in your backend URL. Check out [configuration reference](../4.client/2.configuration.md) for details. Make sure to not have a slash at the end of the URL.
1. Click "Deploy"
1. Congrats! You have your own version of movie-web hosted.
1. You may wish to configure a custom domain - Please consult [the Vercel docs for how to do this](https://vercel.com/docs/getting-started-with-vercel/domains).
// EXPLAIN HOW TO DEPLOY TO CLOUDFLARE with button
## Method 2 - Static Web Host
1. Download the file `movie-web.zip` from the latest release: https://github.com/movie-web/movie-web/releases/latest.
2. Extract the ZIP file so you can edit the files.
3. Open `config.js` in an editor such as Notepad, Visual Studio Code or similar.
4. Put your proxy URL in-between the double quotes of `VITE_CORS_PROXY_URL: ""`. Make sure to not have a slash at the end of your URL.
## Method 2 - docker
// EXPLAIN HOW TO DEPLOY WITH DOCKER
Example (THIS IS AN EXAMPLE, IT WON'T WORK FOR YOU): `VITE_CORS_PROXY_URL: "https://test-proxy.test.workers.dev"`
5. Put your TMDB Read Access Token inside the quotes of `VITE_TMDB_READ_API_KEY: ""`. Please read [the TMDB page](2.tmdb.md) on how to get an API key.
6. If you have a self-hosted backend server, enter your URL in the `VITE_BACKEND_URL` variable. Check out [configuration reference](../4.client/2.configuration.md) for details. Make sure to not have a slash at the end of the URL.
6. Save the file.
7. Upload **all** of the files to a static website hosting such as:
- GitHub Pages
- Netlify
- Vercel
- Etc, there are lots - Google it if the ones above don't work for you.
1. Congrats! You have your own version of movie-web hosted.

19
content/3.client/2.tmdb.md Normal file
View File

@@ -0,0 +1,19 @@
---
title: 'TMDB API Key'
---
## Getting an API Key
In order to search for movies and TV shows, we use an API called "The Movie Database" (TMDB). In order for your client to be able to search, you need to generate an API key.
::alert{type="info"}
The API key is **free**, you just need to create an account.
::
1. Create an account at https://www.themoviedb.org/signup
1. You will be required to verify your email; click the link that you get sent to verify your account.
1. Go to https://www.themoviedb.org/settings/api/request to create a developer account.
1. Read the terms and conditions and accept them.
1. Fill out your details:
- Select "Website" as type of use.
- For the other details can put any values; they are not important.
1. Copy the "API Read Access Token" - **DO NOT COPY THE API Key - IT WILL NOT WORK**

0
content/3.client/2.configuration.md → content/3.client/3.configuration.md
View File

2
content/3.client/3.changelog.md → content/3.client/4.changelog.md
View File

@@ -3,4 +3,4 @@ title: 'Changelog'
---
# Version 4.0.0
Changelog goes here
// CHANGELOG GOES HERE

6
content/3.client/4.upgrade.md
View File

@@ -1,6 +0,0 @@
---
title: 'Upgrade guide'
---
## From `3.*` to `4.0.0`
Upgrade guide goes here

6
content/3.client/5.upgrade.md Normal file
View File

@@ -0,0 +1,6 @@
---
title: 'Upgrade guide'
---
## Upgrade guide
// UPGRADE GUIDE HERE

18
content/4.backend/0.introduction.md
View File

@@ -3,4 +3,20 @@ title: 'Introduction'
---
# Introduction to the backend
// EXPLAIN WHAT THE BACKEND DOES
The backend is essentially just an account server. There is not much more to it.
## Metrics
The backend exposes prometheus metrics, it can be accessed on `/metrics`.
## 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.
## Migrations
To run migrations, You can use the command `pnpm migration:up` inside the docker container.
Alternatively, you can enabled `postgres.migrateOnBoot` and it will be automatically migrated on boot.

23
content/4.backend/1.deploy.md
View File

@@ -3,8 +3,25 @@ title: 'Deploy'
---
# Deploying the backend
// FILL PAGE
The only officially recognized hosting method is through Docker (or similar container runtimes).
## Method 1 - docker
It can be scaled horizontally to all your heart's content.
// EXPLAIN HOW TO DEPLOY WITH DOCKER
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.
::
## Method 1 - Docker
For other versions, [check out the package page](https://github.com/movie-web/backend/pkgs/container/backend).
```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 \
ghcr.io/movie-web/backend:latest
```

130
content/4.backend/2.configuration.md
View File

@@ -3,4 +3,132 @@ title: 'Configuration'
---
# Backend Config Reference
// ADD CONFIGURATION REFERENCE
The config the backend can be provided in 3 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`
This method uses nesting. So the key `server.basePath`. Will result in a json file like this:
```json
{
"server": {
"basePath": "/backend",
}
}
```
## Method 2 - `.env`
This method is a flat method using double underscores as seperators and `MW_` as prefix. So the key `server.basePath`. Will result in the .env file like this:
```sh
MB_SERVER__BASE_PATH=/backend
```
## Method 3 - environment
This method is identical to the `.env` method listed above, but instead of writing it in a file, you add it to the environment.
# Reference
### `server.port`
Port number that the HTTP server listens on.
Example: `8080`
### `server.cors`
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`
### `server.trustProxy`
Should the server trust reverse proxy headers? This is used for ratelimiting
Example: `false`
### `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`
### `logging.format`
Logging format, Should be either `pretty` or `json`.
Example: `pretty`
### `postgres.connection` - REQUIRED
Connection URL for postgres instance, should contain the database in the URL.
Example: `postgresql://localhost:5432`
### `postgres.migrateOnBoot`
Run all migrations that haven't ran yet on boot.
Example: `false`
::alert{type="warn"}
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`
### `crypto.sessionSecret` - REQUIRED
The secret used to sign sessions. Must be at least 32 characters long.
Example: `Make your own`
### `meta.name` - REQUIRED
The name of the backend instance, this will be displayed to users who try to create an account.
Example: `Unofficial movie-web`
### `meta.description`
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.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.
Example: `false`
### `captcha.secret`
Google Recaptcha secret key.
Example: `sjgaJ@3djasFVx`
### `captcha.clientKey`
Google Recaptcha site key.
Example: `2jf853z5bc63bvDb2323FAda`
### `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.
Example: `false`
### `ratelimits.redisUrl`
Redis connection URL for storing ratelimit data. Just uses plain redis without any modules.
Example: `redis://localhost:6379`

11
content/4.backend/3.changelog.md
View File

@@ -1,6 +1,13 @@
---
title: 'Changelog'
---
# Version 1.0.0
# Version 1.1.5
Changelog goes here
Initial version of the backend.
- Prometheus metrics endpoint
- Account creation/deletion endpoints
- Endpoints for importing old account data
- Endpoints for syncing data
- Ratelimit system
- Captcha system

5
content/4.backend/4.upgrade.md
View File

@@ -1,4 +1,7 @@
---
title: 'Upgrade guide'
---
No upgrades to be done yet
# Upgrade guide
There is only one major version, there is nothing to write here yet.