diff --git a/docs/docs/self-hosting/deploy/compose.mdx b/docs/docs/self-hosting/deploy/compose.mdx
index 563cdf946b..57edf063c0 100644
--- a/docs/docs/self-hosting/deploy/compose.mdx
+++ b/docs/docs/self-hosting/deploy/compose.mdx
@@ -8,6 +8,8 @@ import DockerComposeSaSource from '!!raw-loader!./docker-compose-sa.yaml'
import Disclaimer from './_disclaimer.mdx'
import DefaultUser from './_defaultuser.mdx'
import Next from './_next.mdx'
+import NoteInstanceNotFound from './troubleshooting/_note_instance_not_found.mdx';
+
The setup is tested against Docker version 20.10.17 and Docker Compose version v2.2.3
@@ -29,6 +31,8 @@ docker compose up --detach
+
+
## VideoGuide
diff --git a/docs/docs/self-hosting/deploy/knative.mdx b/docs/docs/self-hosting/deploy/knative.mdx
index 813d940c42..975926124b 100644
--- a/docs/docs/self-hosting/deploy/knative.mdx
+++ b/docs/docs/self-hosting/deploy/knative.mdx
@@ -5,6 +5,8 @@ title: Knative
import Disclaimer from './_disclaimer.mdx'
import DefaultUser from './_defaultuser.mdx'
import Next from './_next.mdx'
+import NoteInstanceNotFound from './troubleshooting/_note_instance_not_found.mdx';
+
## Install Knative
@@ -60,6 +62,8 @@ If you didn't configure something else, this is the default IAM admin users logi
* username: zitadel-admin@zitadel.zitadel.default.127.0.0.1.sslip.io
* password: Password1!
+
+
## VideoGuide
diff --git a/docs/docs/self-hosting/deploy/kubernetes.mdx b/docs/docs/self-hosting/deploy/kubernetes.mdx
index 7deab6f65d..ee826fccca 100644
--- a/docs/docs/self-hosting/deploy/kubernetes.mdx
+++ b/docs/docs/self-hosting/deploy/kubernetes.mdx
@@ -5,6 +5,8 @@ title: Kubernetes
import Disclaimer from './_disclaimer.mdx'
import DefaultUser from './_defaultuser.mdx'
import Next from './_next.mdx'
+import NoteInstanceNotFound from './troubleshooting/_note_instance_not_found.mdx';
+
Installation and configuration details are described in the [open source ZITADEL charts repo](https://github.com/zitadel/zitadel-charts).
By default, the chart installs a secure and highly available ZITADEL instance.
@@ -47,6 +49,8 @@ kubectl port-forward svc/my-zitadel 8080
+
+
## Setup ZITADEL and a Service Account Admin
With this setup, you don't create a human user that has the IAM_OWNER role.
diff --git a/docs/docs/self-hosting/deploy/linux.mdx b/docs/docs/self-hosting/deploy/linux.mdx
index dc167aafbf..056752f0eb 100644
--- a/docs/docs/self-hosting/deploy/linux.mdx
+++ b/docs/docs/self-hosting/deploy/linux.mdx
@@ -5,6 +5,8 @@ title: Linux
import Disclaimer from './_disclaimer.mdx'
import DefaultUser from './_defaultuser.mdx'
import Next from './_next.mdx'
+import NoteInstanceNotFound from './troubleshooting/_note_instance_not_found.mdx';
+
## Install CockroachDB
@@ -38,6 +40,8 @@ ZITADEL_EXTERNALSECURE=false ZITADEL_TELEMETRY_ENABLED=true zitadel start-from-i
+
+
## VideoGuide
@@ -54,3 +58,5 @@ This key can be used to provision resources with for example [Terraform](/docs/g
+
+
diff --git a/docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx b/docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx
index e4a668b0fb..b5212b2754 100644
--- a/docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx
+++ b/docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx
@@ -8,6 +8,7 @@ import ExampleTraefikSource from '!!raw-loader!./example-traefik.yaml'
import ExampleZITADELConfigSource from '!!raw-loader!./example-zitadel-config.yaml'
import ExampleZITADELSecretsSource from '!!raw-loader!./example-zitadel-secrets.yaml'
import ExampleZITADELInitStepsSource from '!!raw-loader!./example-zitadel-init-steps.yaml'
+import NoteInstanceNotFound from '../troubleshooting/_note_instance_not_found.mdx';
With this example configuration, you create a near production environment for ZITADEL with [Docker Compose](https://docs.docker.com/compose/).
@@ -71,6 +72,8 @@ This is the IAM admin users login according to your configuration in the [exampl
Read more about [the login process](/guides/integrate/login-users).
+
+
## Troubleshooting
You can connect to cockroach like this: `docker exec -it loadbalancing-example-my-cockroach-db-1 cockroach sql --host my-cockroach-db --certs-dir /cockroach/certs/`
diff --git a/docs/docs/self-hosting/deploy/macos.mdx b/docs/docs/self-hosting/deploy/macos.mdx
index e30bbacdbf..84686f755a 100644
--- a/docs/docs/self-hosting/deploy/macos.mdx
+++ b/docs/docs/self-hosting/deploy/macos.mdx
@@ -5,6 +5,7 @@ title: MacOS
import Disclaimer from './_disclaimer.mdx'
import DefaultUser from './_defaultuser.mdx'
import Next from './_next.mdx'
+import NoteInstanceNotFound from './troubleshooting/_note_instance_not_found.mdx';
## Install CockroachDB
@@ -44,6 +45,7 @@ ZITADEL_EXTERNALSECURE=false ZITADEL_TELEMETRY_ENABLED=true zitadel start-from-i
```
+
## VideoGuide
diff --git a/docs/docs/self-hosting/deploy/troubleshooting/_instance_not_found.mdx b/docs/docs/self-hosting/deploy/troubleshooting/_instance_not_found.mdx
new file mode 100644
index 0000000000..98785275b9
--- /dev/null
+++ b/docs/docs/self-hosting/deploy/troubleshooting/_instance_not_found.mdx
@@ -0,0 +1,5 @@
+`ID=QUERY-n0wng Message=Instance not found`
+
+If you're self hosting with a custom domain, you need to instruct ZITADEL to use the `ExternalDomain`.
+You can find further instructions in our guide about [custom domains](https://zitadel.com/docs/self-hosting/manage/custom-domain).
+We also provide a guide on how to [configure](https://zitadel.com/docs/self-hosting/manage/configure) ZITADEL with variables from files or environment variables.
diff --git a/docs/docs/self-hosting/deploy/troubleshooting/_note_instance_not_found.mdx b/docs/docs/self-hosting/deploy/troubleshooting/_note_instance_not_found.mdx
new file mode 100644
index 0000000000..c194800e6f
--- /dev/null
+++ b/docs/docs/self-hosting/deploy/troubleshooting/_note_instance_not_found.mdx
@@ -0,0 +1,5 @@
+:::note
+This guide is based on a local setup.
+If you encounter an error "Instance Not Found" please read the following section:
+[Instance not found](/docs/self-hosting/deploy/troubleshooting#instance-not-found)
+:::
\ No newline at end of file
diff --git a/docs/docs/self-hosting/deploy/troubleshooting/troubleshooting.mdx b/docs/docs/self-hosting/deploy/troubleshooting/troubleshooting.mdx
new file mode 100644
index 0000000000..aa5b2ed2e0
--- /dev/null
+++ b/docs/docs/self-hosting/deploy/troubleshooting/troubleshooting.mdx
@@ -0,0 +1,10 @@
+---
+title: Troubleshoot
+---
+
+import InstanceNotFound from '/docs/self-hosting/deploy/troubleshooting/_instance_not_found.mdx';
+
+## Instance not found
+
+
+
\ No newline at end of file
diff --git a/docs/docs/support/troubleshooting.md b/docs/docs/support/troubleshooting.mdx
similarity index 91%
rename from docs/docs/support/troubleshooting.md
rename to docs/docs/support/troubleshooting.mdx
index 8027152c34..76d3204638 100644
--- a/docs/docs/support/troubleshooting.md
+++ b/docs/docs/support/troubleshooting.mdx
@@ -29,14 +29,6 @@ To make sure, that your new settings will trigger, please restart your mobile ph
Do you still face this issue? Please contact us, and we will help you find out what the problem is.
-## Instance not found
-
-`ID=QUERY-n0wng Message=Instance not found`
-
-If you're self hosting with a custom domain, you need to instruct ZITADEL to use the `ExternalDomain`.
-You can find further instructions in our guide about [custom domains](https://zitadel.com/docs/self-hosting/manage/custom-domain).
-We also provide a guide on how to [configure](https://zitadel.com/docs/self-hosting/manage/configure) ZITADEL with variables from files or environment variables.
-
## Invalid audience
`invalid audience (APP-Zxfako)`
diff --git a/docs/sidebars.js b/docs/sidebars.js
index bdebfe180a..1d3ce7b10c 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -574,7 +574,8 @@ module.exports = {
"self-hosting/deploy/compose",
"self-hosting/deploy/knative",
"self-hosting/deploy/kubernetes",
- "self-hosting/deploy/loadbalancing-example/loadbalancing-example"
+ "self-hosting/deploy/loadbalancing-example/loadbalancing-example",
+ "self-hosting/deploy/troubleshooting/troubleshooting"
],
},
{