diff --git a/src/content/docs/docs/import-export/backup-and-restore.md b/src/content/docs/docs/import-export/backup-and-restore.md index 18dcaa8..802f507 100644 --- a/src/content/docs/docs/import-export/backup-and-restore.md +++ b/src/content/docs/docs/import-export/backup-and-restore.md @@ -25,9 +25,9 @@ The config file lives on `/data`. Uploaded icons and stored wallpapers live on ` ## A corrupt config -If the config fails to parse, or parses with the wrong shape, Stackyard copies it to `apps.json.corrupt-` and starts empty rather than overwriting the broken one. Each distinct breakage keeps its own backup. +If the config fails to parse, or parses with the wrong shape, Stackyard copies it to `apps.json.corrupt-` and never overwrites the broken one. Each distinct breakage keeps its own backup. Sign-in and saving stay off until the file is fixed, and the dashboard shows the steps to fix it. See [Stackyard cannot read its settings file](/docs/troubleshooting/#stackyard-cannot-read-its-settings-file). -If your dashboard is empty after a restart, look for an `apps.json.corrupt-*` file before making changes. +Restoring an export brings back everything except the password. Set it again in **General**, **Password Protection** straight away. ## Coming from another dashboard diff --git a/src/content/docs/docs/troubleshooting.md b/src/content/docs/docs/troubleshooting.md index 414135c..d58e808 100644 --- a/src/content/docs/docs/troubleshooting.md +++ b/src/content/docs/docs/troubleshooting.md @@ -42,11 +42,27 @@ The page loaded but the API behind it did not answer. The UI is served by nginx Check `docker logs ` for either process failing to start. A data volume that the container's `node` user cannot write to is a common cause. -### My dashboard is empty after a restart +### Stackyard cannot read its settings file + +The dashboard and Settings show this screen when `apps.json` is damaged or cannot be read. Stackyard does not change the file. Sign-in and saving stay off until the file is fixed, so no one can replace your settings or your password. + +There are two causes: + +- **Damaged.** The file is not valid JSON, or it has the wrong shape. Stackyard copies it to `apps.json.corrupt-` in the same folder. Each distinct breakage keeps its own copy. +- **Cannot be read.** The file exists, but the container's `node` user is not allowed to read it. -Look in the data volume for a file named `apps.json.corrupt-`. If the config fails to parse on startup, Stackyard copies it aside and starts empty rather than overwriting it. Your previous config is in that file. +To fix it, on the server: + +1. If the file is damaged, open the copy the screen names, fix the error, and save it as `apps.json`. The container log gives the error and its position. You can instead replace `apps.json` with a file you saved with **Export**. An export holds no password, so set one again in **General**, **Password Protection** straight away. +2. If the file cannot be read, give the `node` user read and write access to `apps.json` in the `data` volume. +3. To start again with no settings, delete `apps.json`. First-time setup then runs. +4. Choose **Check again**. + +The container log shows `config file cannot be used; sign-in and saving are refused until it is fixed`, with the reason and the copy's name. + +### My dashboard is empty after a restart -Otherwise confirm both volumes are mounted. Without `./data` nothing persists. +Confirm both volumes are mounted. Without `./data` nothing persists. ### I updated the image but the UI looks the same @@ -231,6 +247,7 @@ Messages shown in the admin, and what each one means. | `The current password is incorrect.` | The current password typed to change or remove the password did not match. Nothing was saved. | | `The password was changed elsewhere. Reload the page and try again.` | The password changed on another device while this save ran. Nothing was saved. | | `Too many attempts. Try again later.` | 5 wrong passwords from this IP in 15 minutes. Wait, then try again. See [above](#one-persons-failed-logins-lock-everyone-out). | +| `Stackyard cannot use its settings file` | The config file is damaged or cannot be read. Sign-in and saving are off until it is fixed. See [above](#stackyard-cannot-read-its-settings-file). | | `Enter the credential again for: ...` | The request a secret belonged to changed, so the secret was cleared. Re-enter and save. | | `Nothing at that address answered.` | The socket proxy address is unreachable from inside the container. Usually a proxy published on the host's loopback. | | `That name is resolved by Docker, which answers only for containers on a shared network.` | The socket proxy service name is not on a network Stackyard shares. |