Skip to content

docs: major refactor and localization of English documentation #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pandadtdyy merged 2 commits into from
Mar 27, 2026
Merged

docs: major refactor and localization of English documentation #87

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1a15a00
docs: refine en translation
Charles-IX Mar 24, 2026
62c93f6
docs: align english documentation structure strictly with chinese to …
Charles-IX Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 32 additions & 23 deletions content/docs/Hydro/FAQ/debug.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,43 @@
title: Debugging Guide
---

Enter the server console and use `pm2 ls` to check the current list of running processes.
Under normal conditions, there should be four running processes: `hydrooj`, `hydro-sandbox`, `mongodb`, and `caddy`.
If processes are missing, run `pm2 stop all`, then `pm2 del all`, and rerun the installation script.
## Process Management

Check whether each process has started (status is online and uptime is at least one minute).
Access your server console and use `pm2 ls` to view the status of running processes.
A healthy Hydro instance typically has four processes: `hydrooj`, `hydro-sandbox`, `mongodb`, and `caddy`.

If caddy cannot start, it is usually due to port conflicts or errors in `~/.hydro/Caddyfile`; you can try `cd ~/.hydro && caddy run` for details.
If hydro-sandbox cannot start, it is usually due to insufficient permissions / kernel version too low; use `pm2 logs hydro-sandbox --lines 100` for details.
If hydrooj cannot start / does not run properly after starting, see the section below.
If any processes are missing or failing to start:
1. Run `pm2 stop all` and `pm2 del all`.
2. Rerun the installation script to restore the default process configuration.

## hydrooj
### Troubleshooting Process Failures

After stopping with `pm2 stop hydrooj`, run command `hydrooj` directly to run Hydro in the foreground for easier log inspection.
- **Caddy**: Usually fails due to port conflicts (port 80/443 already in use) or syntax errors in `~/.hydro/Caddyfile`. Run `cd ~/.hydro && caddy run` in the foreground to see detailed error messages.
- **Hydro-Sandbox**: Often fails due to insufficient permissions or an outdated kernel. Check logs with `pm2 logs hydro-sandbox --lines 100`.
- **HydroOJ**: If the main service fails, refer to the section below.

1. Try updating to the latest version and check whether it works properly.
2. Back up the plugin list with `cp ~/.hydro/addon.json ~/.hydro/addon.json.bak`.
3. Use `hydrooj addon list` to view plugins, and disable all non-official plugins (those without the `@hydrooj/` prefix) with `hydrooj addon remove <name>`.
4. Restart and check whether it runs properly.
5. If it works, the issue is caused by a third-party plugin. Try re-enabling the plugins you just disabled one by one and check when the issue appears, then contact the plugin provider.
6. If it still does not run properly, provide the development team with the full log from Hydro startup to fault occurrence for troubleshooting.
## Debugging HydroOJ

## Frontend issues
To inspect detailed logs, stop the background process and run Hydro in the foreground:
1. `pm2 stop hydrooj`
2. Run the command `hydrooj` directly.

This refers to frontend pages failing to load (continuous spinner or yellow/red error prompts at the bottom-left).
**Suggested Steps:**
1. **Update**: Ensure you are running the latest version.
2. **Plugins**: Third-party plugins are a common cause of crashes.
- Back up your plugin list: `cp ~/.hydro/addon.json ~/.hydro/addon.json.bak`.
- View active plugins: `hydrooj addon list`.
- Remove non-official plugins (those without the `@hydrooj/` prefix): `hydrooj addon remove <name>`.
3. **Restart**: Check if the system runs correctly without third-party plugins. If it does, re-enable them one by one to identify the culprit.
4. **Support**: If the issue persists, provide the development team with the full console output from startup until the error occurs.

## Frontend Issues

Symptoms include pages failing to load, infinite loading spinners, or error prompts (yellow/red) at the bottom-left of the screen.

1. **Clear Cache**: Press `Ctrl+Shift+Delete` to clear your browser cache and reload.
2. **Browser Version**: Ensure you are using the latest version of Chrome or a Chromium-based browser.
3. **Disable Extensions**: Browser extensions can sometimes interfere with page scripts.
4. **Developer Tools**: Press `F12`, go to the **Console** tab for script errors, and the **Network** tab to identify failed requests.
5. **Report**: When seeking help in the user group, please include screenshots of both the Console and Network tabs.

1. Press `Ctrl+Shift+Delete` to clear browser cache and try again.
2. Update Chrome to the latest version and try again.
3. Same as above, try disabling third-party plugins.
3. If the issue still persists, open F12 Developer Tools, go to the `Console` tab, and check for error messages.
4. Open the `Network` tab and check for failed requests.
5. Report the issue in the group and attach screenshots of the above.
58 changes: 29 additions & 29 deletions content/docs/Hydro/FAQ/index.en.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,15 @@ title: FAQ Collection

## How can I quickly get familiar with system features?

Refer to this post: [https://hydro.ac/discuss/6172ceeed850d38c79ae18f9](https://hydro.ac/discuss/6172ceeed850d38c79ae18f9) for a serverless quick experience of system features.
If you do not need heavy secondary development, we recommend using the online service directly. Problemsets with over 20,000 problems can be copied directly, with no need to buy cloud servers or maintain them manually.
If you need customizations such as binding your own domain or changing logos, you can also enable advanced features in the admin panel yourself.
Refer to this post: [https://hydro.ac/discuss/6172ceeed850d38c79ae18f9](https://hydro.ac/discuss/6172ceeed850d38c79ae18f9) for a serverless quick experience of system features.
If you do not need heavy secondary development, we recommend using the online service directly. Problemsets with over 20,000 problems can be copied directly, with no need to buy cloud servers or maintain them manually.
If you need customizations such as binding your own domain or changing logos, you can also enable advanced features in the admin panel yourself.

Users in the system only support edit and disable, not delete. This is to fundamentally prevent "teaching accidents." Please do not request user deletion features. If you are certain you will never misoperate, develop that feature yourself.

## What is an OJ?

The judging system you are using now is just a program, not artificial intelligence. So in many places, you need to adapt to it. Otherwise, even if your answer is essentially correct, format errors can make the system unable to understand it and still result in wrong answers.
The judging system you are using now is just a program, not artificial intelligence. So in many places, you need to adapt to it. Otherwise, even if your answer is essentially correct, format errors can make the system unable to understand it and still result in wrong answers.
The system workflow is as follows:

- Teachers add problems in the system and strictly define input/output formats.
Expand All @@ -28,11 +28,11 @@ The system workflow is as follows:
- If a student's output is exactly identical to the teacher-provided output, character by character, the program is considered correct; otherwise it is considered wrong.
- If memory/time limits are exceeded during execution, the program is interrupted and marked incorrect.

After understanding the above, students should realize that if a problem does not require prompts like "Please Input Two Number", printing such text yourself will make your output differ from expected output, causing Wrong Answer.
If a problem requires a blank line between every two output lines and you omit it, that is a format error, and vice versa.
You may feel the system is bad for not auto-detecting this; in fact, this is exactly how it effectively trains programming precision and good coding habits. Many strong programmers started by complaining about this system and learned to code carefully and rigorously.
To run all submissions in a unified way, the system must constrain submission format for everyone.
For C/C++ learners, every submission must contain exactly one `main` function, it must return `int`, and preferably return 0, because non-zero return values are considered runtime errors by the operating system.
After understanding the above, students should realize that if a problem does not require prompts like "Please Input Two Number", printing such text yourself will make your output differ from expected output, causing Wrong Answer.
If a problem requires a blank line between every two output lines and you omit it, that is a format error, and vice versa.
You may feel the system is bad for not auto-detecting this; in fact, this is exactly how it effectively trains programming precision and good coding habits. Many strong programmers started by complaining about this system and learned to code carefully and rigorously.
To run all submissions in a unified way, the system must constrain submission format for everyone.
For C/C++ learners, every submission must contain exactly one `main` function, it must return `int`, and preferably return 0, because non-zero return values are considered runtime errors by the operating system.
When a compile error occurs, click the "Compile Error" text link for detailed explanation.

## Error `[ERR_STREAM_PREMATURE_CLOSE]: Premature close` when installing in Arch Linux development mode
Expand Down Expand Up @@ -72,20 +72,20 @@ Manage Domain -> Manage Permissions: disable the "View this domain" permission f
Add a line in system setting `footer_extra_html`: `<a href="https://beian.miit.gov.cn/">XX ICP XX No.</a>`

## What does time mean in contests/assignments? Difference between OI ranking and normal ranking?
Time means the time "spent" for participants to solve a problem:
That is: time solved – contest start time + penalty time
Penalty time = number of wrong submissions before acceptance * 20 minutes.
Normal ranking is based on number of solved problems and "spent" time.
Time means the time "spent" for participants to solve a problem:
That is: time solved – contest start time + penalty time
Penalty time = number of wrong submissions before acceptance * 20 minutes.
Normal ranking is based on number of solved problems and "spent" time.
OI ranking is based on score. Problems can be scored proportionally by pass ratio, 100 points each. If you want non-uniform score distribution, use config.

## Where does the script install OJ?

You can get Hydro's default location with `yarn global dir`. (Do not modify code directly; updates will overwrite all changes there. Use the plugin API instead.)
Default database files are in `/data/db`, but do not copy files directly; `hydrooj backup` is recommended.
Files such as test data are stored in `/data/file`.
You can get Hydro's default location with `yarn global dir`. (Do not modify code directly; updates will overwrite all changes there. Use the plugin API instead.)
Default database files are in `/data/db`, but do not copy files directly; `hydrooj backup` is recommended.
Files such as test data are stored in `/data/file`.
Config files are in `/root/.config/hydro` and `/root/.hydro`.
For production servers in operation, always make an offline backup before any operation.
Always unzip backup files to verify all data is included, and check backup size (large systems should have backups of hundreds of MB). If possible, verify restore success in a VM.
For production servers in operation, always make an offline backup before any operation.
Always unzip backup files to verify all data is included, and check backup size (large systems should have backups of hundreds of MB). If possible, verify restore success in a VM.

## What is the precision of time limit and memory limit?

Expand All @@ -102,7 +102,7 @@ Then try again.

## I want Python to support numpy and similar libraries. What should I do?

If installed before 2022/8/12, run `pip3 install numpy` then `pm2 restart hydro-sandbox`.
If installed before 2022/8/12, run `pip3 install numpy` then `pm2 restart hydro-sandbox`
Otherwise refer to the [Compiler](./install/compiler) section.

## I forgot MongoDB account/password after using installation script. What should I do?
Expand All @@ -123,8 +123,8 @@ User Hydro (uid = 1) is only for sending system messages (similar to 10000 in QQ

## How to modify website icon?

Use `hydrooj addon create` to create a plugin, which will create `/root/addon` automatically.
Go to `/root/addon/public`, and place your site icons there.
Use `hydrooj addon create` to create a plugin, which will create `/root/addon` automatically.
Go to `/root/addon/public`, and place your site icons there.
You need these files in that directory (for different browsers):

- `favicon-16x16.png`
Expand All @@ -134,7 +134,7 @@ You need these files in that directory (for different browsers):
- `android-chrome-192x192.png`
- `apple-touch-icon-180x180.png`

Matching resolution is recommended but not mandatory. These images are shown on browser tabs.
Matching resolution is recommended but not mandatory. These images are shown on browser tabs.
You also need this file in that directory:

- `nav_logo_dark.png`
Expand Down Expand Up @@ -182,7 +182,7 @@ Enter MongoDB and execute the following (replace placeholders in angle brackets

```sh
use hydro
db.user.update({"_id": <用户 UID>}, {$set: {"badge": "<标签内容>#<背景颜色（HEX）>#<文字颜色（HEX）>"}})
db.user.update({"_id": <USER UID>}, {$set: {"badge": "<Label>#<Background HEX>#<Text HEX>"}})
```

## Why can't I batch download multiple files?
Expand All @@ -192,8 +192,8 @@ Otherwise, download files one by one (Ctrl+click filename).

## Why is there no language option on my submission page?

Problem -> Judge Settings -> Allowed languages
Domain Settings -> Edit Domain Profile -> Allowed languages
Problem -> Judge Settings -> Allowed languages
Domain Settings -> Edit Domain Profile -> Allowed languages
In both places, fill language IDs separated by English commas. If unsure, leave empty.

## The 'yarn global' commands have been remove in 2.x - consider using 'yarn dlx' or a third-party plugin instead
Expand All @@ -202,13 +202,13 @@ If you cannot understand this issue, just use the installation script and do not

## I'm in a computer lab environment; many users share one IP and trigger rate limits. How to solve?

Option 1: Set up a proxy server in the intranet and forward intranet IPs to the server. (Recommended)
Option 2: Use commands like `hydrooj cli system set limit.user_login 999` to set new rate limits (the error page shows which limit was triggered)
Option 1: Set up a proxy server in the intranet and forward intranet IPs to the server. (Recommended)
Option 2: Use commands like `hydrooj cli system set limit.user_login 999` to set new rate limits (the error page shows which limit was triggered)
Option 3: Start with `pm2 start hydrooj -- --benchmark` to disable all rate limits (Not recommended)

## Adjust temporary directory size

Judge stores temporary files in /dev/shm, including contestants' output, compiled executables, etc. These files are automatically deleted after judging.
Judge stores temporary files in /dev/shm, including contestants' output, compiled executables, etc. These files are automatically deleted after judging.
If you set high parallel judging, pay attention to /dev/shm size limit. We usually recommend reserving at least 512MB.

Check /dev/shm size:
Expand All @@ -221,4 +221,4 @@ Adjust /dev/shm size:

```bash
sudo mount -o remount,size=1024M /dev/shm
```
```
68 changes: 36 additions & 32 deletions content/docs/Hydro/FAQ/upgrade.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,40 +2,44 @@
title: Upgrade Guide
---

Run `yarn global upgrade-interactive --latest`, then press Space to select **all** packages except pm2 for upgrade, and press Enter to confirm.
Then restart the service with `pm2 restart hydrooj`.
After restart, if `pm2 logs hydrooj --lines 100` shows no errors and you see `Server started`, then everything is fine.
When installing/upgrading plugins, be sure to upgrade the system first. Mixing old and new versions may cause various unexpected issues.
Also, if you have plugins installed from URLs like `hydrooj install https://xxxx`, rerun that command during system upgrade to update those plugins.

All historical Hydro versions can be upgraded to the latest version without data loss. If you have questions about upgrading older systems, join the official group and ask the group owner anytime.

The following are issues you may encounter during upgrade:

## Remove nvm

In very early versions, Hydro used nvm to manage the Node.js environment. This setup has been deprecated. If your system has nvm, you can remove it with `rm -rf ~/.nvm`;
Check whether nix is installed. If not, install nix first with `. <(curl https://hydro.ac/nix.sh)`;
Reinstall the Node.js environment with nix: `nix-env -iA nixpkgs.nodejs nixpkgs.yarn nixpkgs.pm2`

## How to handle `NodeJS >= xx required` errors?

First read the nvm section above.
## Recommended Upgrade Path

To upgrade your Hydro instance to the latest version:
1. Run: `yarn global upgrade-interactive --latest`
2. Use the spacebar to select **all** packages except for `pm2`.
3. Press Enter to confirm.
4. Restart the service: `pm2 restart hydrooj`
5. Verify success: Check logs with `pm2 logs hydrooj --lines 100`. Look for the "Server started" message.

**Important Considerations:**
- Always upgrade the system before adding or updating plugins to avoid compatibility issues.
- If you have installed plugins from URLs (e.g., `hydrooj install https://...`), re-run those install commands after a system upgrade to ensure the plugins are also updated.
- All historical versions of Hydro are designed for a seamless upgrade to the latest version. If you have any questions, please contact the official user group.

## Common Upgrade Issues

### 1. Removing nvm
Early versions of Hydro relied on `nvm` to manage the Node.js environment. This approach is now deprecated in favor of Nix.
- If `nvm` is present, you can remove it: `rm -rf ~/.nvm`.
- Ensure Nix is installed: `. <(curl https://hydro.ac/nix.sh)`.
- Use Nix to reinstall core components: `nix-env -iA nixpkgs.nodejs nixpkgs.yarn nixpkgs.pm2`.

### 2. "NodeJS >= xx required" Errors
If you see a version error during upgrade:
1. Check for `nvm` as described above.
2. Update your Nix channels: `nix-channel --update`.
3. Reinstall Node.js and Yarn via Nix: `nix-env -iA nixpkgs.nodejs nixpkgs.yarn nixpkgs.pm2`.
4. Proceed with the upgrade steps.
5. Use `pm2 restart hydrooj --update-env` to apply the environment changes.

### 3. Upgrading the Sandbox
If the system displays a warning that your sandbox version is critically low or vulnerable to security issues, follow these steps:

```bash
nix-channel --update
nix-env -iA nixpkgs.nodejs nixpkgs.yarn nixpkgs.pm2
# Continue the upgrade steps
yarn global upgrade-interactive --latest
pm2 restart hydrooj --update-env
```

## Upgrade sandbox

If you encounter `Your sandbox version is tooooooo low!` or `Your sandbox version is vulnerable to symlink escape issue`, please upgrade the sandbox:

```bash
nix-channel --update
nix-env -e hydro.sandbox && nix-env -iA nixpkgs.go-judge && ln -sf $(which go-judge) /usr/bin/hydro-sandbox
nix-env -e hydro.sandbox
nix-env -iA nixpkgs.go-judge
ln -sf $(which go-judge) /usr/bin/hydro-sandbox
pm2 restart hydro-sandbox --update-env
```

Loading