feat: initial commit
This commit is contained in:
DecDuck
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: Creating a library
|
||||
---
|
||||
To import games and start using Drop, you must first create a library to import from.
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Exposing your instance
|
||||
---
|
||||
|
||||
Exposing your instance allows it to be accessible from other computers than the one you're hosting it on.
|
||||
|
||||
## Setting `EXTERNAL_URL`
|
||||
|
||||
Drop uses `EXTERNAL_URL` for creating invitation links, OIDC redirects, and everything else. It should be passed as an environment variable, and include the protocol, ip/domain, and port (if applicable). Examples include:
|
||||
|
||||
- `http://192.168.0.100:3000`
|
||||
- `https://drop.my.domain/`
|
||||
- `http://drop.home.arpa:3000`
|
||||
|
||||
Drop automatically parses and formats the URL, so there are no requirements on the format, as long as it is a valid URL.
|
||||
|
||||
## LAN
|
||||
|
||||
The `compose.yaml` provided in the [Quickstart guide](../quickstart.md) already exposes the Drop instance on port 3000. If you're on the same LAN as your Drop instance, you can find it's IP and then use:
|
||||
|
||||
```
|
||||
http://[instance IP]:3000
|
||||
```
|
||||
|
||||
as the connection URL when setting up your Drop client.
|
||||
|
||||
## Reverse Proxy
|
||||
|
||||
If you are unsure how to set up a reverse proxy, or even what one is, this guide isn't for you. There are far better guides out there, so follow them to set up your reverse proxy.
|
||||
|
||||
There is no special configuration required to run Drop behind a reverse proxy.
|
||||
|
||||
## VPN
|
||||
|
||||
If you are unsure how to set up a VPN for remote access, please find and follow a far better guide than this one.
|
||||
|
||||
Accessing Drop over a VPN works very similarly to [accessing via LAN](#lan), so follow those steps.
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Admin stuff
|
||||
---
|
||||
|
||||
# Admin description
|
||||
|
||||
jdkajsdkas
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: GiantBomb
|
||||
---
|
||||
|
||||
import { Steps } from "@astrojs/starlight/components";
|
||||
|
||||
:::caution
|
||||
GiantBomb has recently be acquired, and their API is undergoing significant changes. The GiantBomb metadata provider currently **does not work.**
|
||||
:::
|
||||
|
||||
GiantBomb is a community-driven open game database. It is accessible at [https://www.giantbomb.com/](https://www.giantbomb.com/).
|
||||
|
||||
<Steps>
|
||||
1. **Creating an account**
|
||||
|
||||
To get an API key, you must sign up for an account. Head over to [GiantBomb's Login or Signup](https://www.giantbomb.com/login-signup/) page to create your account, and follow the prompts.
|
||||
|
||||
2. **Getting an API key**
|
||||
|
||||
Head over to the [GiantBomb API page](https://www.giantbomb.com/api/) and copy your API key from the box at the top of the page.
|
||||
|
||||
3. **Add to your `compose.yaml`**
|
||||
|
||||
Then, set your API key in your environment variables with a key of `GIANT_BOMB_API_KEY`:
|
||||
|
||||
```diff
|
||||
drop:
|
||||
image: ghcr.io/drop-oss/drop:latest
|
||||
...
|
||||
environment:
|
||||
- DATABASE_URL=postgres://drop:drop@postgres:5432/drop
|
||||
- EXTERNAL_URL=http://localhost:3000 # default, customise if accessing from another computer or behind a reverse proxy
|
||||
+ - GIANT_BOMB_API_KEY=[api key]
|
||||
```
|
||||
|
||||
|
||||
</Steps>
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: IGDB
|
||||
---
|
||||
|
||||
import { Steps } from "@astrojs/starlight/components";
|
||||
|
||||
IGDB is a game database run by Twitch. It is free to use, but requires a Twitch account.
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Follow the instructions at [https://api-docs.igdb.com/#getting-started](https://api-docs.igdb.com/#getting-started)
|
||||
|
||||
:::tip
|
||||
You must have a Twitch account to use IGDB.
|
||||
:::
|
||||
|
||||
2. Assign the `IGDB_CLIENT_ID` and `IGDB_CLIENT_SECRET` environment variables in your `compose.yaml`:
|
||||
|
||||
```diff
|
||||
drop:
|
||||
image: ghcr.io/drop-oss/drop:latest
|
||||
...
|
||||
environment:
|
||||
- DATABASE_URL=postgres://drop:drop@postgres:5432/drop
|
||||
- EXTERNAL_URL=http://localhost:3000 # default, customise if accessing from another computer or behind a reverse proxy
|
||||
+ - IGDB_CLIENT_ID=[your client ID]
|
||||
+ - IGDB_CLIENT_SECRET=[your client secret]
|
||||
```
|
||||
|
||||
</Steps>
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: PCGamingWiki
|
||||
---
|
||||
|
||||
PCGamingWiki is a community run game database. There no additional setup required to use PCGamingWiki.
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: Steam
|
||||
---
|
||||
|
||||
Drop can fetch game data from Steam. There is no additional configuration required to use Steam metadata.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Quickstart
|
||||
---
|
||||
This guide quickly runs through how to get set up with Drop in about five minutes, depending on your experience.
|
||||
|
||||
## Setting up the instance
|
||||
|
||||
The easiest way to get Drop running is using our pre-built Docker container.
|
||||
|
||||
```yaml compose.yaml
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:14-alpine
|
||||
healthcheck:
|
||||
test: pg_isready -d drop -U drop
|
||||
interval: 30s
|
||||
timeout: 60s
|
||||
retries: 5
|
||||
start_period: 10s
|
||||
volumes:
|
||||
- ./db:/var/lib/postgresql/data
|
||||
environment:
|
||||
- POSTGRES_PASSWORD=drop
|
||||
- POSTGRES_USER=drop
|
||||
- POSTGRES_DB=drop
|
||||
drop:
|
||||
image: ghcr.io/drop-oss/drop:latest
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
ports:
|
||||
- 3000:3000
|
||||
volumes:
|
||||
- ./library:/library
|
||||
- ./data:/data
|
||||
environment:
|
||||
- DATABASE_URL=postgres://drop:drop@postgres:5432/drop
|
||||
- EXTERNAL_URL=http://localhost:3000 # default, customise if accessing from another computer or behind a reverse proxy
|
||||
```
|
||||
|
||||
**The main things in this `compose.yaml` is the volumes attached to the `drop` service:**
|
||||
|
||||
1. `./library` is where you will put your games to be imported into Drop. See '[Structuring your library](../library.md#structuring-your-library)' once you're set up.
|
||||
2. `./data` is where Drop will store anything that's using the default file-system backed storage system. Typically, these are objects.
|
||||
|
||||
**In addition, configure your chosen metadata provider:**
|
||||
|
||||
- [GiantBomb](../metadata/giantbomb.md)
|
||||
- [IGDB](../metadata/igdb.md)
|
||||
- [PCGamingWiki](../metadata/pcgamingwiki.md)
|
||||
- Manual - you can import games without metadata and enter it yourself.
|
||||
|
||||
:::tip
|
||||
If you want to, you can generate a more secure PostgreSQL username & password.
|
||||
:::
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Example Guide
|
||||
description: A guide in my new Starlight docs site.
|
||||
---
|
||||
|
||||
Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
|
||||
Writing a good guide requires thinking about what your users are trying to do.
|
||||
|
||||
## Further reading
|
||||
|
||||
- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework
|
||||
@@ -1,17 +1,16 @@
|
||||
---
|
||||
title: Welcome to Starlight
|
||||
description: Get started building your docs site with Starlight.
|
||||
template: splash # Remove or comment out this line to display the site sidebar on this page.
|
||||
title: Welcome to Drop
|
||||
description: Welcome to the Drop OSS project documentation.
|
||||
hero:
|
||||
tagline: Congrats on setting up a new Starlight project!
|
||||
image:
|
||||
file: ../../assets/houston.webp
|
||||
actions:
|
||||
- text: Example Guide
|
||||
link: /guides/example/
|
||||
- text: Quickstart
|
||||
link: /admin/quickstart
|
||||
icon: right-arrow
|
||||
- text: Read the Starlight docs
|
||||
link: https://starlight.astro.build
|
||||
- text: Download client
|
||||
link: https://droposs.org/download
|
||||
icon: external
|
||||
variant: minimal
|
||||
---
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Example Reference
|
||||
description: A reference page in my new Starlight docs site.
|
||||
---
|
||||
|
||||
Reference pages are ideal for outlining how things work in terse and clear terms.
|
||||
Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting.
|
||||
|
||||
## Further reading
|
||||
|
||||
- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Library Sources
|
||||
tableOfContents:
|
||||
minHeadingLevel: 1
|
||||
maxHeadingLevel: 2
|
||||
---
|
||||
|
||||
import { FileTree } from "@astrojs/starlight/components";
|
||||
|
||||
Drop supports different library structures, but they all are underpinned by the same few concepts. You can add more than one library (called a 'library source') that each use different structures, to combine your multiple game libraries into one.
|
||||
|
||||
:::note
|
||||
|
||||
A **game** in Drop is associated with all the metadata. You do not need to have a version available to import a game.
|
||||
|
||||
A **version** in Drop is associated with the files and content, and needs it to be imported. Versions also include information on how to install and run the game.
|
||||
|
||||
:::
|
||||
|
||||
# Drop-style
|
||||
|
||||
The Drop style library format enables all the Drop features, but isn't compatible with many other applications.
|
||||
|
||||
## Structuring your library
|
||||
|
||||
Drop uses a very particular structure to organise your games library. Generally, to get started, you need to create two folders for a game:
|
||||
|
||||
<FileTree>
|
||||
- MyGame *game folder, contains versions*
|
||||
- version-1 *version folder, contains the content*
|
||||
- game.exe
|
||||
- ...
|
||||
- version-2
|
||||
- ...
|
||||
- MyOtherGame
|
||||
- version1.zip *optionally, **instead of the folder**, the version can be a compressed archive*
|
||||
- version2/
|
||||
- ...
|
||||
|
||||
</FileTree>
|
||||
|
||||
In the UI, you'll be prompted to "import" each folder separately:
|
||||
|
||||
- Importing the **game folder** will link the folder to a game in the metadata database, and pulls the metadata (images, descriptions, that sort of thing) from one of your configured metadata providers. **This only happens once for each game you have.**
|
||||
- Importing **version** will read the entirety of the game files and generate checksums and metadata that clients need to download the games with. **This happens for each new version you add.**
|
||||
|
||||
### Importing more versions
|
||||
|
||||
So your game has gotten an update and you've got new files. All you need to do is create a new version folder inside the game folder, and move all the files you have into that folder. Then, import it within the Drop admin UI.
|
||||
|
||||
If you have files that you're supposed to **paste over the previous version**, Drop supports that! Read [Update mode](./update-mode.mdx) to find out more.
|
||||
|
||||
# Flat-style or 'compat'
|
||||
|
||||
This is a more commonly used layout for game libraries, but doesn't support all of Drop's features. It's useful when you want to migrate to Drop from another application or having an existing library. **We recommend [Drop-style](#drop-style) libraries if you're starting from scratch**.
|
||||
|
||||
## Structuring your library
|
||||
|
||||
In flat-style, the game and version folders/files are combined into one:
|
||||
|
||||
<FileTree>
|
||||
- MyGame *game folder **and** version folder combined*
|
||||
- game.exe *game content isn't in a subfolder*
|
||||
- ...
|
||||
- MyOtherGame.zip *same as before, can optionally be an archive**
|
||||
</FileTree>
|
||||
|
||||
In Drop, you will still need to import the game and version separately as described above, but **the version will simply be called 'default'**.
|
||||
|
||||
# Archive support
|
||||
Drop uses [7zip](https://www.7-zip.org/) under the hood to provide archive support, and therefore inherits its impressive list of supported formats.
|
||||
|
||||
For quick reference, the supported list of archives is: 7z, XZ, BZIP2, GZIP, TAR, ZIP, WIM, APFS, AR, ARJ, CAB, CHM, CPIO, CramFS, DMG, EXT, FAT, GPT, HFS, IHEX, ISO, LZH, LZMA, MBR, MSI, NSIS, NTFS, QCOW2, RAR, RPM, SquashFS, UDF, UEFI, VDI, VHD, VHDX, VMDK, XAR and Z.
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Update Mode
|
||||
---
|
||||
|
||||
import { FileTree } from "@astrojs/starlight/components";
|
||||
|
||||
Update mode allows admins to store multiple versions of a game, without needing to store duplicate files.
|
||||
|
||||
In practice, update mode _pastes_ versions over each other to create the final content. This is particularly useful, as many updates that are not provided through distribution networks are provided as patches.
|
||||
|
||||
## Example
|
||||
|
||||
Let's say you have the following version setup:
|
||||
|
||||
<FileTree>
|
||||
- mygame
|
||||
- v1.0.0
|
||||
- mygame.exe
|
||||
- content1.zip
|
||||
- content2.zip
|
||||
- content3.zip
|
||||
- v1.5.3
|
||||
- content2.zip
|
||||
- content3.zip
|
||||
- v1.9.1
|
||||
- mygame.exe
|
||||
- content3.zip
|
||||
|
||||
</FileTree>
|
||||
|
||||
With versions `v1.0.0`, `v1.5.3`, `v1.9.1` imported in order, where v1.9.1 has the highest priority.
|
||||
|
||||
|
||||
If versions `v1.5.3` and `v1.9.1` are set in **update mode**, when the user downloads the latest version (`v1.9.1`), they get:
|
||||
<FileTree>
|
||||
- mygame-v1.9.1
|
||||
- mygame.exe *v1.9.1*
|
||||
- content1.zip *v1.0.0*
|
||||
- content2.zip *v1.5.3*
|
||||
- context3.zip *v1.9.1*
|
||||
</FileTree>
|
||||
|
||||
As you can see, the files in the newer versions overwrite the files from the older versions.
|
||||
@@ -0,0 +1,5 @@
|
||||
:root {
|
||||
--sl-color-accent-low: hsl(224, 100%, 60%);
|
||||
--sl-color-accent: hsl(224, 100%, 60%);
|
||||
--sl-color-accent-high: hsl(224, 100%, 60%);
|
||||
}
|
||||
Reference in New Issue
Block a user