docs(testing): setup guide

docs/testing/testing-setup.md

@@ -0,0 +1,94 @@
+---
+title: Beta Testing Setup
+unlisted: true
+---
+
+# Beta Testing Setup
+
+Thank you for helping us test the latest features! This guide will help you set up a **local testing environment** that stays completely separate from your "real" book library.
+
+## 📦 Prerequisites
+
+Before you start, you need to have [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed on your computer.
+
+## 🚀 Setup Guide
+
+### **Step 1. Create a Sandbox Folder**
+
+To prevent any risk to your actual data, create a brand new folder on your computer (e.g., `booklore-test`). Do all your work inside this folder.
+
+### **Step 2. Prepare Configuration Files**
+
+Copy your existing `.env` and `docker-compose.yml` files into this new sandbox folder.
+
+:::info[For new users]
+Follow Steps 1–3 in the [Installation Guide](docs/installation.md#-installation-steps) to create these files from scratch.
+:::
+
+### **Step 3. Modify `docker-compose.yml`**
+
+Open the `docker-compose.yml` file in your sandbox folder using a text editor (Notepad, TextEdit, VS Code) and apply these changes:
+
+#### **A. Point to the Latest Pre-release Image:**
+
+Find the line starting with `image:` and update it with the latest `develop-` tag provided by the team at https://github.com/booklore-app/booklore/pkgs/container/booklore/
+
+```yaml
+booklore:
+  image: booklore/booklore:develop-2f6e8570
+  # Alternative: ghcr.io/booklore-app/booklore:develop-2f6e8570
+```
+
+#### **B. Avoid Container Conflicts:**
+
+To prevent your computer from getting confused between your "real" Booklore and this "test" version, you must give the `container_name` a unique name.
+
+```yaml
+booklore:
+  container_name: booklore-test
+
+mariadb:
+  container_name: mariadb-test
+```
+
+### **Step 4. Launch Test Environment**
+
+Open your terminal or command prompt inside your sandbox folder and run:
+`docker compose up -d`
+
+**Access the app at:** [http://localhost:6060](http://localhost:6060)
+
+---
+
+## 🔧 Troubleshooting
+
+| Error Message                      | Solution                                                                                                     |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| "container name is already in use" | Ensure your test containers have a unique name. Refer to Step 3B.                                            |
+| "port is already allocated"        | Your "real" Booklore (or another app) is likely still running. Stop it and try `docker compose up -d` again. |
+
+### Checking Logs
+
+If the app doesn't start or crashes, the logs will tell us why. Run these in your terminal:
+
+- **Booklore Logs:** `docker compose logs booklore`
+- **Database Logs:** `docker compose logs mariadb`
+
+### Resetting the Test Database
+
+As a last resort, if the testing data becomes corrupted and you want a fresh start:
+
+:::danger[Database Reset Warning]
+This deletes all library metadata inside your testing environment. Books remain but need re-importing.
+:::
+
+1. Stop the containers: Run `docker compose down -v`
+2. Delete the folder: `./mariadb/config` (inside your test directory)
+3. Restart: `docker compose up -d`
+
+---
+
+## 💡 Tester Tips
+
+- **Isolate Instances:** We strongly recommend stopping your "real" Booklore instance while testing the "Beta" version. This prevents confusion and keeps your computer's resources focused on the test.
+- **Small Batches:** Don't import your whole library at once. Test the new features with 5–10 books first to ensure everything is stable.

sidebars.ts

@@ -124,6 +124,19 @@ const sidebars: SidebarsConfig = {
       ],
     },
   ],
+
+  // Testing sidebar
+  testingSidebar: [
+    {
+      type: 'category',
+      label: 'Booklore Beta Testing',
+      collapsible: true,
+      collapsed: false,
+      items: [
+        'testing/testing-setup',
+      ],
+    },
+  ],
 };
 
 export default sidebars;