Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

feat(docs): add v1-migration entry to metadata

Bill Yang8c6b3afb5150
diff --git a/docs/src/content/_meta.js b/docs/src/content/_meta.js
index 244ce95cf..679365dfd 100644
--- a/docs/src/content/_meta.js
+++ b/docs/src/content/_meta.js
@@ -17,6 +17,7 @@ export default {
"self-hosting": "",
"self-hosting-advanced": "",
"self-hosting-nginx": "",
+ "v1-migration": "",
_6: {
type: "separator",
title: "Settings",
diff --git a/docs/src/content/v1-migration.mdx b/docs/src/content/v1-migration.mdx
new file mode 100644
index 000000000..31a2a0ca6
--- /dev/null
+++ b/docs/src/content/v1-migration.mdx
@@ -0,0 +1,95 @@
+import { Callout } from 'nextra/components'
+
+# Migration to v1.0
+
+This guide covers the breaking changes and migration steps when upgrading to Rybbit v1.0.
+
+## API Path Changes
+
+In v1.0, we've simplified the reverse proxy configuration by having the backend expect requests with the `/api/` prefix. This eliminates the need for custom path rewriting in reverse proxy configurations.
+
+### If You're Using the Built-in Caddy Server
+
+**No action required.** The built-in Caddy server configuration has been automatically updated and will work without any changes on your part.
+
+### If You're Using a Custom Reverse Proxy
+
+**You need to remove any custom API path rewriting** from your reverse proxy configuration.
+
+<Callout type="warning">
+ **Important:** If you were using a custom reverse proxy (Nginx, Apache, etc.) with path rewriting rules for the `/api/` endpoint, you must remove these rules when upgrading to v1.0.
+</Callout>
+
+#### What to Remove
+
+Remove any configuration that strips or rewrites the `/api/` prefix when forwarding requests to the backend. Common examples include:
+
+**Nginx - Remove these patterns:**
+```nginx
+# ❌ Remove this type of configuration
+location /api/ {
+ rewrite ^/api(/.*)$ $1 break; # Remove this line
+ proxy_pass http://localhost:3001/; # Change trailing slash
+}
+```
+
+**Update to:**
+```nginx
+# βœ… Correct v1.0 configuration
+location /api/ {
+ proxy_pass http://localhost:3001; # No trailing slash, no rewrite
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+**Apache - Remove these patterns:**
+```apache
+# ❌ Remove this type of configuration
+ProxyPass /api/ http://localhost:3001/
+ProxyPassReverse /api/ http://localhost:3001/
+```
+
+**Update to:**
+```apache
+# βœ… Correct v1.0 configuration
+ProxyPass /api/ http://localhost:3001/api/
+ProxyPassReverse /api/ http://localhost:3001/api/
+```
+
+**Docker Compose with custom location rules:**
+```yaml
+# ❌ Remove rewrite rules like this
+location /api/ {
+ rewrite ^/api(/.*)$ $1 break;
+ proxy_pass http://rybbit_backend:3001;
+}
+```
+
+**Update to:**
+```yaml
+# βœ… Correct v1.0 configuration
+location /api/ {
+ proxy_pass http://rybbit_backend:3001;
+}
+```
+
+#### Why This Change?
+
+This change simplifies the reverse proxy setup and eliminates a common source of configuration errors. The backend now handles the `/api/` prefix internally, making the setup more straightforward and consistent across different proxy solutions.
+
+## Migration Steps
+
+1. **Backup your current configuration** before making any changes
+2. **Update your reverse proxy configuration** to remove API path rewriting (if applicable)
+3. **Update to v1.0** using the update script:
+ ```bash
+ ./update.sh
+ ```
+4. **Verify your setup** by checking that your Rybbit instance is accessible and functioning correctly
+
+## Need Help?
+
+If you encounter issues during migration or need assistance with your specific reverse proxy setup, feel free to join our Discord community for support.
\ No newline at end of file