From 06b388231b7f6da2ec4b7a6c6935cd02e1954e27 Mon Sep 17 00:00:00 2001 From: Matthew Lopez <73856503+MatthewL246@users.noreply.github.com> Date: Mon, 27 May 2024 22:20:51 -0400 Subject: [PATCH] Begin updating the docs to use Docusaurus features --- docs/docs/setup/requirements.md | 27 +++++--- docs/docs/setup/safety.md | 40 ++++++++---- docs/docs/setup/server-setup.md | 111 +++++++++++++++++++++++--------- docs/docs/welcome.md | 6 +- docs/docusaurus.config.ts | 1 + 5 files changed, 132 insertions(+), 53 deletions(-) diff --git a/docs/docs/setup/requirements.md b/docs/docs/setup/requirements.md index 9396ac5..fa353fd 100644 --- a/docs/docs/setup/requirements.md +++ b/docs/docs/setup/requirements.md @@ -4,14 +4,18 @@ sidebar_position: 1 # System requirements +Before you start setting up the Pretendo Network server, make sure your system meets the following requirements. + ## Hardware -- A decent CPU (at least 4 cores recommended, must be capable of - [running MongoDB](https://www.mongodb.com/docs/ops-manager/current/tutorial/provisioning-prep/)) -- At least 10 GB of free storage for Docker image, build cache, and server data (using an SSD is strongly recommended, - as it will also be used for database storage) -- At least 4GB of free RAM while building the Docker containers; the servers themselves uses about 1GB of RAM while - running +- A decent CPU + - At least 4 cores are recommended + - Must fulfill the + [MongoDB system requirements](https://www.mongodb.com/docs/ops-manager/current/tutorial/provisioning-prep/) +- At least 4GB of free RAM while building the Docker containers + - The servers themselves uses about 1GB of RAM while running +- At least 10 GB of free storage for Docker images, build cache, and server data + - Using an SSD is strongly recommended, as it will be used for databases - Network connectivity to the client console ## Operating system @@ -22,12 +26,19 @@ sidebar_position: 1 | Linux (Docker Engine) | ✅ Working | | macOS (Docker Desktop) | ❓ Untested\* | -_\*macOS is untested because I don't own a Mac. In theory, it should work._ +_\*macOS is untested because I don't own the hardware to test it with. In theory, it should work._ ## Software +### Required + - [Git](https://git-scm.com/downloads/) - [Docker](https://docs.docker.com/get-docker/) - [Docker Compose](https://docs.docker.com/compose/install/) -Everything else runs inside Docker containers. +### Recommended + +- [The tnftp FTP client](https://en.wikipedia.org/wiki/Tnftp), which is used for automatically uploading files to the + client consoles. This is most likely a package in your distro's package manager repo. + +Everything else runs inside Docker containers, so it does not need to be installed. diff --git a/docs/docs/setup/safety.md b/docs/docs/setup/safety.md index bc4d790..fad923e 100644 --- a/docs/docs/setup/safety.md +++ b/docs/docs/setup/safety.md @@ -4,18 +4,34 @@ sidebar_position: 3 # Safety -**Back up your data!** If you lose your MongoDB database, you will lose all of your PNIDs and Juxt posts. If you have a -PNID signed in on a Wii U, you will also be **stuck with a useless account on your console that you can't delete** -because deleting an account requires a server to authenticate the password. Creating a new account on your server with -the same PNID won't work because each PNID has a numerical ID that is appended to the end of the password before -hashing, so your console will not authenticate with the new PNID. Use the included `./scripts/backup.sh` script to back -up all of your Pretendo server data. +Remember to follow these safety guidelines when using your server. -**Don't delete the `pretendo-network-*` Docker volumes**. You will permanently lose your database (see above) and all of -your Pretendo server data. If you need to do something risky, run a backup first. +:::danger[Danger: Back up your server data!] -**Don't use the same P/NNID username on multiple servers.** This applies to NNIDs and PNIDs on the official Pretendo -Network server. +If you lose your server database, you will lose all of your PNIDs and Juxt posts. You will also need to take manual +steps to remove your self-hosted PNID from your consoles, as they will not be able to authenticate with an account that +does not exist on the server. **Use the included script `./scripts/backup.sh` script to back up all of your Pretendo +server data regularly.** -**Always verify that you are actually connecting to your own server.** The easiest way is to check the mitmproxy logs to -see if you are getting the expected HTTP requests. +::: + +:::danger[Don't delete the `pretendo-network-*` Docker volumes!] + +You will permanently lose your database (see above) and all of your Pretendo server data. If you need to do something +risky, run a backup first. If you need to fully reset your environment, use the included script +`./scripts/full-reset.sh` to do so safely by running a backup first. + +::: + +:::warning[Don't use the same P/NNID username on multiple servers.] + +This applies to NNIDs, PNIDs on the official Pretendo Network server, and PNIDs on your self-hosted server. The consoles +will not work right if you attempt to use multiple accounts with the same username. + +::: + +:::warning[Always verify that you are actually connecting to your own server.] + +The easiest way is to check the mitmproxy logs to see if you are getting the expected HTTP requests. + +::: diff --git a/docs/docs/setup/server-setup.md b/docs/docs/setup/server-setup.md index 3834fe4..9e0af19 100644 --- a/docs/docs/setup/server-setup.md +++ b/docs/docs/setup/server-setup.md @@ -4,35 +4,86 @@ sidebar_position: 2 # Server setup -Note that this guide assumes that you are **familiar with using the Linux command line** and have a **basic -understanding of Docker**. +This guide will help you download, set up, and run the Pretendo Network server software on your system. -1. Check the [system requirements](./requirements.md) and install any necessary software. -2. Clone this repo with Git. Make sure to recursively checkout submodules: - `git clone --recurse-submodules https://github.com/MatthewL246/pretendo-docker.git` - - **Note:** Downloading this repo as a ZIP file from GitHub will **not** work because it uses - [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for the Pretendo Network repos. - - If you are using Windows, you should clone the repo **inside your WSL distro** for multiple reasons. First, this - avoids Git messing with line endings and breaking shell scripts as it can do when you clone a repo in Windows (due - to `autocrlf`). Second, this maximizes performance because Docker runs inside WSL and copying files between WSL and - Windows is slow. -3. Optionally, dump your console's BOSS keys for the BOSS (SpotPass) server. These keys are required if you want to - create new SpotPass content. These steps are based on - [the guide from the boss-crypto repository](https://github.com/PretendoNetwork/boss-crypto/#dumping-crypto-keys). - - For the Wii U: Download [Full_Key_Dumper](https://github.com/EpicUsername12/Full_Key_Dumper/releases) and run the - ELF from a Tiramisu (not Aroma) environment. Then, copy the `sd:/boss_keys.bin` file from your SD card to the - `console-files` directory in this repo. - - For the 3DS: Download the - [Citra key dumper GodMode9 script](https://raw.githubusercontent.com/citra-emu/citra/master/dist/dumpkeys/DumpKeys.gm9) - and run it in GodMode9. Then, copy the `sd:/gm9/aes_keys.txt` file from your SD card to the `console-files` - directory in this repo. - - Finally, run `./scripts/get-boss-keys.sh` to validate the dumped keys. It will show you if the keys are missing or - incorrect. -4. Run the initial setup script (`./setup.sh`) from your WSL distro and follow its instructions. - - **Note:** This will take some time to build the required Docker images, and it will use up to 8GB of bandwidth to - download images. - - After initial setup, use `docker compose up -d` to start the containers. -5. Open [127.0.0.1:8081](http://127.0.0.1:8081) in your browser to view the mitmproxy web interface. This is where you - can view a live list of HTTP requests from client devices. +:::info -Next, choose where you want to connect from. +This guide assumes that you are already **familiar with using the Linux command line** and have a **basic understanding +of Docker**. + +::: + +## Downloading + +Clone this repo with Git. Make sure to recursively checkout submodules. + +```shell +git clone --recurse-submodules https://github.com/MatthewL246/pretendo-docker.git +``` + +:::warning + +Downloading this repo as a ZIP file from GitHub will **not** work because it uses +[Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for the Pretendo Network repos. + +::: + +:::tip + +If you are using Windows, you should clone the repo **inside your WSL distro** for multiple reasons. + +- This avoids Git messing with line endings and breaking shell scripts, which it can do when you clone a repo in Windows + (due to `autocrlf`). +- This maximizes performance because Docker runs inside WSL and copying files between WSL and Windows is slow. + +Remember that **all shell commands should be run inside WSL**, not Git Bash in Windows. + +::: + +## Setting up + +:::note[Optional: dumping BOSS keys] + +You may dump the BOSS keys from one or both consoles for use by the BOSS (SpotPass) server. These keys are **only +required if you want to create new SpotPass content**. + +_These steps are based on the +[guide from the boss-crypto repository](https://github.com/PretendoNetwork/boss-crypto/#dumping-crypto-keys)._ + +1. **For Wii U:** Download [Full Key Dumper](https://github.com/EpicUsername12/Full_Key_Dumper/releases) and run the ELF + from the Tiramisu environment (this program does not support Aroma). Then, copy the `SD:/boss_keys.bin` file from + your SD card to the `console-files` directory in this repo. +2. **For 3DS:** Download the + [Citra key dumper GodMode9 script](https://raw.githubusercontent.com/PabloMK7/citra/master/dist/dumpkeys/DumpKeys.gm9) + and run it in GodMode9. Then, copy the `SD:/gm9/aes_keys.txt` file from your SD card to the `console-files` directory + in this repo. +3. Finally, run `./scripts/get-boss-keys.sh` to validate the dumped keys. It will show you if the keys are missing or + incorrect. + +::: + +Open a terminal window inside the repository's directory. Run the initial setup script and follow its instructions. + +```shell +./setup.sh +``` + +:::info + +This will take some time to build the required Docker images, and it will use up to 8GB of bandwidth to download images. + +::: + +After initial setup, use Docker Compose to build and start the server containers. + +```shell +docker compose up -d --build +``` + +:::tip + +You can now open [127.0.0.1:8081](http://127.0.0.1:8081) in your browser to view the mitmproxy web interface. This is +where you can view a live list of HTTP requests from client devices, which is incredibly useful for understanding what +requests are hitting your server. + +::: diff --git a/docs/docs/welcome.md b/docs/docs/welcome.md index a098418..274ad0a 100644 --- a/docs/docs/welcome.md +++ b/docs/docs/welcome.md @@ -8,7 +8,7 @@ sidebar_label: Welcome This documentation will help you get started with running your own self-hosted Pretendo Network server! -You can learn more about this project [on GitHub](https://github.com/MatthewL246/pretendo-docker) and learn more about -the Pretendo Network [on their website](https://pretendo.network/). +You can learn more about this project at [the GitHub repo](https://github.com/MatthewL246/pretendo-docker) and learn +more about the Pretendo Network on [their website](https://pretendo.network/). -Get started by [continuing to the next page](./setup/requirements.md). +Get started by [continuing to the setup guide](./setup/requirements.md). diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 124724e..90a1d3f 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -66,6 +66,7 @@ const config: Config = { ], }, prism: { + additionalLanguages: ["bash"], theme: prismThemes.github, darkTheme: prismThemes.dracula, },