Domain and SSL Management

Configure custom domains and SSL certificates for your applications and services

Overview

Dokploy provides comprehensive domain and SSL certificate management through Traefik integration. You can configure custom domains with automatic SSL certificates via Let’s Encrypt, or bring your own certificates.

Domain Configuration

Adding a Domain

Domains can be attached to applications, compose services, and preview deployments.

1. Navigate to your service

   Open your application or compose service in the Dokploy dashboard.

2. Access domain settings

   Click on the Domains tab to manage domain configurations.

3. Add domain

   Click Add Domain and configure the following:

   • Host: Your domain name (e.g., example.com or app.example.com)
   • Port: Internal container port (default: 3000)
   • Path: External path prefix (default: /)
   • HTTPS: Enable secure connections
   • Certificate Type: Choose SSL certificate method

Domain Types

Dokploy supports three domain types:

Application

Domains for standalone applications deployed through Dokploy.

{
  domainType: "application",
  host: "app.example.com",
  port: 3000,
  https: true,
  certificateType: "letsencrypt"
}

Compose

Domains for Docker Compose services. Requires serviceName to target a specific service.

{
  domainType: "compose",
  host: "api.example.com",
  port: 8080,
  serviceName: "api",
  https: true,
  certificateType: "letsencrypt"
}

Preview

Domains for preview deployments, typically used for testing branches or PRs.

{
  domainType: "preview",
  host: "preview-123.example.com",
  port: 3000,
  https: true,
  certificateType: "none"
}

Advanced Path Configuration

Dokploy supports advanced routing with path manipulation:

Internal Path

The internalPath field defines the path prefix forwarded to your container.

Example: External request to /api/users can be forwarded to /users internally:

{
  host: "example.com",
  path: "/api",
  internalPath: "/",
  stripPath: true
}

Strip Path

When stripPath is enabled, the path prefix is removed before forwarding to the container.

Without stripPath: /api/users → container receives /api/users

With stripPath: /api/users → container receives /users

{
  path: "/api",
  stripPath: true,
  internalPath: "/"
}

Traefik.me Domains

Dokploy can auto-generate domains using the traefik.me wildcard DNS service. This is useful for quick testing without configuring DNS.

Traefik.me domains automatically resolve to your server’s IP address using a pattern like: appname-hash-1-2-3-4.traefik.me where 1-2-3-4 represents your server IP.

SSL Certificate Management

Certificate Types

Dokploy supports three SSL certificate configuration methods:

Let's Encrypt

Automatic SSL certificates with auto-renewal via ACME protocol.

Best for: Production domains with valid DNS

Custom Certificate

Use your own SSL certificates from any Certificate Authority.

Best for: Enterprise setups, wildcard certificates

None

HTTP only, no SSL encryption.

Best for: Development, internal services behind VPN

Let’s Encrypt Configuration

Automatic SSL certificates are issued and renewed by Let’s Encrypt through Traefik.

1. Enable HTTPS

   Toggle HTTPS when adding or editing a domain.

2. Select Let's Encrypt

   Choose Certificate Type: letsencrypt

3. Verify DNS

   Ensure your domain’s DNS A record points to your Dokploy server’s IP address.

4. Deploy

   Save the configuration. Traefik will automatically request and configure the certificate.

Let’s Encrypt certificates are stored in /etc/dokploy/traefik/dynamic/acme.json and are automatically renewed before expiration.

Let’s Encrypt Configuration Details

Traefik uses the HTTP-01 challenge method:

certificatesResolvers:
  letsencrypt:
    acme:
      email: [e-mail]
      storage: /etc/dokploy/traefik/dynamic/acme.json
      httpChallenge:
        entryPoint: web

Let’s Encrypt has rate limits: 50 certificates per registered domain per week. Use staging environment for testing.

Custom Certificates

Upload and manage your own SSL certificates for complete control.

1. Prepare certificate files

   You need:

   • Certificate file (PEM format)
   • Private key file (PEM format)
   • Optional: CA bundle/intermediate certificates
2. Upload certificate

   Navigate to Settings → Certificates and click Add Certificate:

   • Name: Descriptive name for the certificate
   • Certificate Data: Paste full certificate chain
   • Private Key: Paste private key
   • Auto Renew: Enable if using automated renewal
3. Configure domain

   When adding a domain:

   • Set Certificate Type: custom
   • Enter Custom Cert Resolver: Name matching your certificate

Certificate Storage

Custom certificates are stored securely in the database and mounted to Traefik:

• Path: /etc/dokploy/traefik/certificates/<certificate-name>.crt
• Key Path: /etc/dokploy/traefik/certificates/<certificate-name>.key
• Permissions: 600 (owner read/write only)

Wildcard Certificates

Use custom certificates for wildcard domain coverage:

// Upload wildcard certificate for *.example.com
{
  name: "example-wildcard",
  certificateData: "-----BEGIN CERTIFICATE-----\n...",
  privateKey: "-----BEGIN PRIVATE KEY-----\n...",
  autoRenew: true
}

// Configure domains using the wildcard cert
[
  {
    host: "api.example.com",
    certificateType: "custom",
    customCertResolver: "example-wildcard"
  },
  {
    host: "app.example.com",
    certificateType: "custom",
    customCertResolver: "example-wildcard"
  }
]

Domain Validation

Dokploy includes domain validation to verify DNS configuration before deployment.

Validation Process

The validation checks:

1. DNS Resolution: Domain resolves to the correct IP
2. Port Accessibility: Target port is reachable
3. Certificate Validity: SSL certificate matches the domain (if HTTPS)

// Validation API
await validateDomain({
  domain: "app.example.com",
  serverIp: "192.168.1.100" // Optional: validate against specific IP
});

Multi-Server Domains

For multi-server deployments, domains can be configured per server:

{
  host: "app.example.com",
  serverId: "server-123",
  certificateType: "letsencrypt"
}

Each server maintains its own Let’s Encrypt certificates and Traefik configuration.

Troubleshooting

SSL Certificate Not Issued

Symptoms: Domain shows insecure or certificate errors

Solutions:

• Verify DNS points to correct server IP
• Check port 80 is accessible for HTTP-01 challenge
• Review Traefik logs: docker logs dokploy-traefik
• Verify /etc/dokploy/traefik/dynamic/acme.json permissions are 600

Domain Not Routing

Symptoms: 404 or connection refused errors

Solutions:

• Verify container is running and healthy
• Check port mapping matches domain configuration
• Inspect Traefik dashboard for routing rules
• Ensure no conflicting domain configurations

Certificate Renewal Failed

Symptoms: Expired certificate warnings

Solutions:

• Check Traefik logs for renewal errors
• Verify server has outbound internet access
• Ensure DNS still points to correct IP
• Manual renewal: restart Traefik container

Best Practices

Use Let's Encrypt for Production

Automatic certificate management reduces operational overhead and ensures certificates stay current.

Wildcard Certs for Multiple Subdomains

If managing many subdomains, use a custom wildcard certificate to simplify configuration.

Test with Traefik.me First

Validate your application works with auto-generated domains before configuring custom DNS.

Enable stripPath for APIs

API gateways often expect paths without prefixes. Use stripPath: true to remove routing prefixes.

API Reference

Domain management is available via API:

// Create domain
POST /api/trpc/domain.create
{
  host: "example.com",
  port: 3000,
  https: true,
  certificateType: "letsencrypt",
  applicationId: "app-123"
}

// Update domain
POST /api/trpc/domain.update
{
  domainId: "domain-456",
  https: true,
  certificateType: "custom",
  customCertResolver: "my-cert"
}

// Delete domain
POST /api/trpc/domain.delete
{
  domainId: "domain-456"
}

See API Reference for complete documentation.