docs: enhance domain configuration documentation with detailed explanations of Internal Path and Strip Path middlewares

This commit is contained in:
Jhonatan Caldeira
2025-07-05 15:38:24 -03:00
parent 18e4b0ce29
commit 557ea6cb27

View File

@@ -41,15 +41,82 @@ Associate custom domains with your application to make it accessible over the in
- **Host**: The domain name that you want to link to your application (e.g., `api.dokploy.com`).
- **Path**: The specific path within the domain where the application should be accessible.
- **Internal Path**: The internal path where your application expects to receive requests.
- **Strip Path**: Removes the **Path** from the request before forwarding to the application.
- **Container Port**: The port on the container that the domain should route to.
- **HTTPS**: Toggle this on to enable HTTPS for your domain, providing secure, encrypted connections.
- **Certificate**: Select (letsencrypt) or (None)
For how **Internal Path** and **Strip Path** work using Traefik middlewares, see the note below.
### Note
Proper domain configuration is crucial for the accessibility and security of your application. Always verify domain settings and ensure that DNS configurations are properly set up to point to the correct IP addresses. Enable HTTPS to enhance security and trust, especially for production environments.
### Understanding Internal Path and Strip Path
Dokploy uses Traefik middlewares to modify request paths before they reach your application. These powerful tools allow you to create flexible routing configurations that match your application's expected URL structure.
<Callout type="warn">
**Warning: Potential Redirect Issues**
When using Internal Path and Strip Path middlewares, ensure your application is properly configured to handle the modified paths. If your application generates redirects or absolute URLs that don't match the expected path structure, it may cause redirect loops or broken functionality. Use these middlewares with caution and test thoroughly to ensure your application works correctly with the path transformations.
</Callout>
**Internal Path Middleware**
The Internal Path middleware adds a prefix to the request path before forwarding it to your container. This is useful when your application expects all requests to start with a specific base path.
**Example:**
- Domain: `api.dokploy.com`
- Path: `/v1`
- Internal Path: `/backend/api`
- Request: `api.dokploy.com/v1/users`
- Forwarded to container as: `/backend/api/users`
In this example, the middleware adds `/backend/api` to the beginning of the request path, which is helpful when your application is structured to expect requests at a specific internal directory.
**Strip Path Middleware**
The Strip Path middleware removes a specified path prefix from the request before forwarding it to your container. This is perfect when you want to organize your public URLs with prefixes but your application expects clean, unprefixed paths.
**Example:**
- Domain: `app.dokploy.com`
- Path: `/dashboard`
- Strip Path: Enabled
- Request: `app.dokploy.com/dashboard/settings`
- Forwarded to container as: `/settings`
Here, the middleware removes the `/dashboard` prefix, so your application receives the request as if it was made directly to `/settings`.
**Using Both Internal Path and Strip Path Together**
You can combine both middlewares to create sophisticated routing scenarios. When both are enabled, Strip Path is applied first, then Internal Path is added.
**Example:**
- Domain: `service.dokploy.com`
- Path: `/public`
- Strip Path: Enabled
- Internal Path: `/app/v2`
- Request: `service.dokploy.com/public/api/users`
- Processing:
1. Strip Path removes `/public`: `/api/users`
2. Internal Path adds `/app/v2`: `/app/v2/api/users`
- Final forwarded path: `/app/v2/api/users`
This powerful combination allows you to:
- Remove public-facing path prefixes that users see
- Add internal path prefixes that your application requires
- Create clean separation between your public URL structure and internal application structure
**When to Use Each Option**
- **Internal Path only**: When your application requires a specific base path that differs from your public URL
- **Strip Path only**: When you want organized public URLs but your application expects clean paths
- **Both together**: When you need to transform public URLs to match complex internal application structures
These middlewares ensure your application receives requests in the exact format it expects, regardless of how you structure your public domain paths.
### Important Clarification on Container Ports