Skip to content

Commit c1ec3d6

Browse files
DecDuckDecDuck
committed
feat: add more guides and command parsing
1 parent 10032a2 commit c1ec3d6

7 files changed

Lines changed: 238 additions & 1 deletion

File tree

‎astro.config.mjs‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,18 @@ export default defineConfig({
3232
items: [
3333
{ slug: "admin/guides/exposing" },
3434
{ slug: "admin/guides/creating-library" },
35+
{ slug: "admin/guides/import-game" },
36+
{ slug: "admin/guides/import-version" },
3537
],
3638
},
3739
{
3840
label: "Metadata",
3941
autogenerate: { directory: "admin/metadata" },
4042
},
43+
{
44+
label: "Authentication",
45+
autogenerate: { directory: "admin/authentication" },
46+
},
4147
],
4248
},
4349
{
@@ -48,5 +54,5 @@ export default defineConfig({
4854
customCss: ["./src/styles/drop.css"],
4955
}),
5056
],
51-
site: "https://docs-next.droposs.org/"
57+
site: "https://docs-next.droposs.org/",
5258
});

‎src/content/docs/admin/authentication/oidc.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: OpenID Connect
3+
---
4+
5+
OpenID Connect is a OAuth2 extension support by most identity providers.
6+
7+
## Configure OpenID Connect
8+
9+
To configure OIDC, you must set the following environment variables:
10+
11+
| Variable | Usage |
12+
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
13+
| `OIDC_CLIENT_ID` | Client ID from your identity provider. |
14+
| `OIDC_CLIENT_SECRET` | Client secret from your identity provider. |
15+
| `OIDC_ADMIN_GROUP` | Grant admin to users with this group configured in your identity provider. Tested with Authentik. |
16+
| `OIDC_USER_GROUP` (optional) | Optionally require a OIDC group to sign in. By default, Drop will allow any user. |
17+
| `DISABLE_SIMPLE_AUTH` (optional) | Disable simple auth |
18+
| `OIDC_USERNAME_CLAIM` (optional) | Change the field that Drop pulls the username claim from. Users are merged based on their usernames. Defaults to "preferred_username". |
19+
| `OIDC_PROVIDER_NAME` (optional) | Change the name of the OIDC provider that is displayed on the sign-in page. Default is "external provider". |
20+
| `OIDC_DONT_REQUIRE_HTTPS` (optional) | Flag to disable HTTPS requirement for OIDC providers. |
21+
22+
---
23+
24+
And then, you must configure **either**:
25+
26+
#### Use `OIDC_WELLKNOWN`
27+
28+
A unprotected endpoint that returns a OIDC well-known JSON. Fetched on startup
29+
30+
---
31+
32+
#### Provide options individually
33+
34+
| Variable | Usage |
35+
| -------------------- | ------------------------------------------------------------------------- |
36+
| `OIDC_AUTHORIZATION` | Authorization endpoint. Usually ends with `authorize`. |
37+
| `OIDC_TOKEN` | Token endpoint. Usually ends with `token`. |
38+
| `OIDC_USERINFO` | Userinfo endpoint. Usually ends with `userinfo`. |
39+
| `OIDC_SCOPES` | Comma separated list of scopes. Requires, at least, `openid` and `email`. |
40+
| `OIDC_ISSUER` | OIDC issuer URL. Usually provided by the OIDC provider. |
41+
| `OIDC_JWKS` | OIDC JWKS validation URL. |
42+
43+
## Redirect URL
44+
45+
Drop uses the `EXTERNAL_URL` environment variable to create the callback URL: `$EXTERNAL_URL/auth/callback/oidc`.

‎src/content/docs/admin/authentication/simple.mdx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: Simple
3+
---
4+
5+
import { Steps } from "@astrojs/starlight/components";
6+
7+
Simple authentication (or simple auth) is a basic username and password combination. It's the default for Drop, and is the fallback authentication mechanism if Drop is unable to initialise any others.
8+
9+
Simple authentication works on a system of invites.
10+
11+
## Creating an Invite
12+
13+
<Steps>
14+
1. Head to your Drop Admin dashboard, and click on the **'Users' tab.**
15+
16+
2. Then, head to the authentication panel by **clicking the 'Authentication &rarr;' button.**
17+
18+
3. Then, **click on the "Simple" auth**, **click the three-dot menu**, and **"Configure"**.
19+
20+
4. Then, create an invite with the button and modal.
21+
22+
</Steps>
23+
24+
## Disabling Simple Auth
25+
26+
If you've configured another authentication mechanism, you can disable simple by setting the environment variable `DISABLE_SIMPLE_AUTH` to "true".

‎src/content/docs/admin/guides/import-game.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Importing a game
3+
---
4+
5+
import { Steps } from "@astrojs/starlight/components";
6+
7+
Once you've got a library set up, you can import a game.
8+
9+
## Set up metadata providers
10+
11+
Drop's metadata provider system allows you to import from a variety of metadata sources from one interface. **By default, there are a couple metadata providers that require no configuration to be activated.** You can use those for now.
12+
13+
If you'd like to configure more metadata providers, use the metadata section on the sidebar to view individual configurations for each provider.
14+
15+
## Importing a game
16+
17+
<Steps>
18+
1. **Create your game folder.**
19+
20+
Following your chosen library structure, create a game folder with a name similar _enough_ to the published title of your game.
21+
22+
For example, if your game is called "STAR WARS: Jedi Survivor - Deluxe Edition", you can usually get away with just "Jedi Survivor".
23+
24+
2. **Open import interface.**
25+
26+
Once you've created your game folder, open the Admin Dashboard, and navigate to the "Library" tab. **Drop should detect you have a new game to import**, and display an alert. **Use the "Import" button to proceed.**
27+
28+
All games in Drop must be **manually imported** - there is no automatic library matching. However, some automation tools may use the Drop API to automatically import games and versions on your behalf.
29+
30+
If Drop does not detect your new game folder, double check your library structure and library source configuration. If the issue persists, hop into our Discord or open an issue on GitHub.
31+
32+
3. **Select your game folder.**
33+
34+
From the dropdown at the top of the page, select your game folder.
35+
36+
This starts a metadata search, using the name of the folder. Results will appear in another dropdown, in which you can select the correct option. You can also edit the search parameters and click Search again, to refine your results. Once you've found the correct option, click "Import".
37+
38+
You can also skip this process by using the manual metadata provider, by clicking "Import without metadata"
39+
40+
:::tip
41+
**Bulk import mode** can be used to import many games in succession. It turns off the redirect to the imoprt task.
42+
:::
43+
44+
4. **Wait for import.**
45+
46+
Once you've clicked import, Drop will redirect you to the import task. It will show the progress and any log messages about the import.
47+
48+
:::note
49+
The import happens in the background, so you can leave the page without worrying about cancelling the import.
50+
:::
51+
52+
</Steps>

‎src/content/docs/admin/guides/import-version.mdx‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Importing a version
3+
---
4+
5+
import { Steps } from "@astrojs/starlight/components";
6+
7+
Once you've got a library set up, and have imported a game, you can import a version for that game.
8+
9+
<Steps>
10+
1. ### **Add your version files.**
11+
Following your library structure, copy over your version files to your version directory. Make sure you verify the game works, and you know how to launch it properly.
12+
2. ### **Open import wizard.**
13+
14+
Head over to your Admin Dashboard, and click on the "Library" tab. Drop should detect that you have a new version to import. To open the import wizard, you can either click on the alert on any game tile, or click "Open in Editor" and navigate to the "Versions" tab.
15+
16+
3. ### **Select your version folder.**
17+
18+
From the dropdown, select your version folder. It should load for a little bit, and give you an interface that looks something like this:
19+
20+
![Version import wizard for an example game](./version-import-wizard.png)
21+
22+
4. ### _About the wizard..._
23+
24+
Here's what each section is about:
25+
26+
### Setup executable/command
27+
28+
Setup executables are run after download but before first launch, and are useful for extracting files or setting necessary configuration.
29+
30+
:::tip
31+
Both setup and launch command configurations may provide suggestions based on file extension. To view these suggestions, start typing or click the chevron in the text field.
32+
:::
33+
34+
### Setup mode
35+
36+
Setup mode removes the requirement of at least one launch command. Useful for installer-only versions. Clients will never show a launch button, only a setup button.
37+
38+
### Launch executable/command
39+
40+
Launch executables can be launched by the user. If multiple launch commands are configured, they will all be shown to the user on launch to pick from.
41+
42+
:::note
43+
For a version to show up on a platform, **at least one launch command of that platform needs to be configured**, unless the version is in setup-only mode.
44+
:::
45+
46+
### Update mode
47+
48+
Update mode is for when you're importing a patch. **You have to re-add the launch/setup commands, they are not preserved from previous versions.**
49+
50+
5. ### **Import your version.**
51+
52+
There are many different kinds of imports, but for simplicity's sake, we'll do either a portable or installer version.
53+
54+
### Portable version
55+
56+
A portable version can be launched from an executable. To import a portable game, add a launch command with the portable game executable.
57+
58+
### Installer version
59+
60+
A installer version uses "setup mode". Enable the option, and then add the installer executable in setup commands.
61+
62+
:::note
63+
Setup and launch commands are parsed in a cross-platform, POSIX style. It's not relevant for simple setups, but useful to know. Read more about it in [Command Parsing](/reference/command-parsing/).
64+
:::
65+
66+
6. ### **Wait for import.**
67+
68+
Drop will redirect you to a task page about the import. A version import scales with the size of the version, since the import will read through every file in the version and generate checksums.
69+
70+
:::note
71+
As with the game import, feel free to leave the import page while it's going, without worrying about it cancelling.
72+
:::
73+
74+
</Steps>

‎src/content/docs/admin/guides/version-import-wizard.png‎

102 KB
Loading

‎src/content/docs/reference/command-parsing.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Command Parsing
3+
---
4+
5+
Drop uses a cross-platform, POSIX inspired command parsing for a consistent way to define launch commands in a single string.
6+
7+
The basic format is:
8+
9+
```bash
10+
MY_ENV_KEY=myvalue MY_OTHER_ENV_KEY=myothervalue mycommand --myargs --myotherargs "other string"
11+
```
12+
13+
Drop will split this into three parts:
14+
| | |
15+
| - | - |
16+
| Environment variables | Collects anything that has a `=` at the start. (`MY_ENV_KEY=myvalue MY_OTHER_ENV_KEY=myothervalue`) |
17+
| Command | The next value (`mycommand`) |
18+
| Arguments | Everything else (`--myargs --myotherargs "other string"`) |
19+
20+
These will be passed in platform-specific process creation functions.
21+
22+
## Platform-specific behaviour
23+
24+
On Linux and macOS (Unix), the command will be reassembled into a single string, and then executed on the system shell, meaning shell expansions and other utilities work. Drop will respect quotes (`"`) to preserve spaces.
25+
26+
On Windows, the command isn't reassembled, and environment variables, command, and args are passed directly to the process creation.
27+
28+
## Format args
29+
30+
| Key | Value description |
31+
| ----------- | ---------------------------------------------------------------------------------- |
32+
| `{dir}` | The current working directory/install directory. |
33+
| `{exe}` | The relative name of the executable. The command from above parsing. |
34+
| `{abs_exe}` | The absolute path of the executable, the command appended to the install directory |

0 commit comments

Comments
 (0)