From 7214380f79121da0b74190c24cfdf0becaf8025f Mon Sep 17 00:00:00 2001 From: Mauricio Siu Date: Sun, 30 Nov 2025 02:00:01 -0600 Subject: [PATCH] docs: add troubleshooting section for 404 errors with Templates and Compose Services - Introduced guidance on resolving 404 errors related to Traefik routing for services created from templates and Docker Compose. - Explained the differences in routing configuration between Applications and Templates/Compose Services. - Provided a step-by-step solution for configuring domains and redeploying services to ensure changes take effect. --- .../content/docs/core/troubleshooting.mdx | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/apps/docs/content/docs/core/troubleshooting.mdx b/apps/docs/content/docs/core/troubleshooting.mdx index ea0ffbf..a3564ca 100644 --- a/apps/docs/content/docs/core/troubleshooting.mdx +++ b/apps/docs/content/docs/core/troubleshooting.mdx @@ -163,6 +163,37 @@ port: 3000 1. Remove the healthcheck from the service 2. Make sure the healthcheck is working +## Templates and Compose Services Returning 404 + +If you're experiencing 404 errors when accessing services created from templates (like Docker Registry, Stalwart, Uptime Kuma, etc.) or Docker Compose services, this is usually related to how Traefik handles routing for different service types. + +### Understanding the Difference + +Dokploy uses two different methods for configuring Traefik routing: + +1. **Applications** (Nixpacks, Dockerfile, Buildpacks): Use the Traefik **file system** for routing configuration + - Domain changes are applied automatically + - No need to redeploy after updating domains + - Configuration files are created in Traefik's dynamic configuration directory + +2. **Templates and Compose Services**: Use Traefik **labels** for routing configuration + - Require redeployment after any domain changes + - Labels are read from Docker container metadata + - Learn more about Traefik labels in the [official documentation](https://doc.traefik.io/traefik/reference/routing-configuration/other-providers/docker/#configuration-examples) + +### Solution + +When working with Templates or Compose services: + +1. **Configure your domain** in the Domains section of your service +2. **Redeploy the service** - This is crucial! The domain changes won't take effect until you redeploy +3. Wait for the deployment to complete +4. Your service should now be accessible via the configured domain + + + **Key Tip:** Every time you add, modify, or remove a domain from a Template or Compose service, you must redeploy for the changes to take effect. + + ## Getting "Bad Gateway Error" When Accessing Your Application Domain If you're encountering a Bad Gateway Error when accessing your application through its domain, this typically indicates one of several common configuration issues: