Preview Deployments

Automatically deploy and test pull requests with preview environments

Preview deployments allow you to automatically create temporary environments for pull requests, enabling you to test changes before merging to production.

Overview

When enabled, Dokploy automatically:

1. Detects new pull requests
2. Creates an isolated deployment
3. Assigns a unique preview URL
4. Updates the PR with the deployment status
5. Cleans up when the PR is closed or merged

Preview deployments are only available for applications using GitHub, GitLab, Bitbucket, or Gitea as source providers.

Enabling Preview Deployments

1. Navigate to Application

   Open your application settings in Dokploy.

2. Enable Preview Deployments

   Go to the “Preview Deployments” tab and toggle the feature on.

3. Configure Settings

   Set the following options:

   • Preview Wildcard Domain: Base domain for preview URLs
   • Preview Limit: Maximum number of concurrent previews (default: 3)
   • Preview Port: Application port for the preview (default: 3000)
   • Preview Path: Base path for the application (default: /)
   • Preview HTTPS: Enable SSL for preview deployments
   • Require Collaborator Permissions: Restrict previews to repository collaborators only
4. Save Configuration

   Click “Save” to activate preview deployments.

Preview URL Structure

Dokploy generates unique URLs for each preview deployment:

# Pattern
<branch-name>-<pr-number>.<wildcard-domain>

# Examples
feature-auth-123.preview.myapp.com
bugfix-api-456.preview.myapp.com
release-v2-789.preview.myapp.com

Ensure your wildcard domain is configured with a wildcard DNS record:

*.preview.myapp.com → your-server-ip

Preview Configuration

Environment Variables

Define preview-specific environment variables:

# Preview Environment Variables
NODE_ENV=preview
DEBUG=true
API_URL=https://${DOKPLOY_DEPLOY_URL}/api
ENABLE_ANALYTICS=false

DOKPLOY_DEPLOY_URL is automatically injected and contains the full preview URL.

Build Arguments

Override build arguments for preview builds:

# Preview Build Arguments
NEXT_PUBLIC_API_URL=${DOKPLOY_DEPLOY_URL}/api
NEXT_PUBLIC_ENV=preview
BUILD_ID=${PR_NUMBER}

Build Secrets

Use separate credentials for preview deployments:

# Preview Build Secrets
NPM_TOKEN=${PREVIEW_NPM_TOKEN}
GITHUB_TOKEN=${PREVIEW_GITHUB_TOKEN}

Custom Labels

Add Docker labels to preview containers:

[
  "preview=true",
  "pr.number=${PR_NUMBER}",
  "pr.branch=${BRANCH_NAME}"
]

Security Configuration

Require Collaborator Permissions

When enabled, preview deployments only trigger for users with write access to the repository:

Enabled (Recommended)

✅ Repository collaborators → Preview created
❌ External contributors → Preview skipped

This prevents malicious code execution from untrusted contributors.

Disabled

⚠️ All pull requests → Preview created

Only disable if you trust all contributors. External PRs could execute arbitrary code.

Watch Paths

Limit preview deployments to specific file changes:

# Only deploy previews when these paths change
/apps/frontend/**
/packages/ui/**
/shared/**

If configured, previews only deploy when the PR modifies files matching these patterns.

Preview Lifecycle

1. Pull Request Opened

1. Webhook Received

   Dokploy receives webhook from your Git provider.

2. Permission Check

   If “Require Collaborator Permissions” is enabled, verify the PR author has write access.

3. Watch Path Check

   If watch paths are configured, verify at least one modified file matches.

4. Deployment Created

   Dokploy creates a new preview deployment with:

   Name: pr-${PR_NUMBER}
   Branch: ${PR_BRANCH}
   URL: ${BRANCH}-${PR_NUMBER}.${WILDCARD_DOMAIN}
   
5. Build & Deploy

   Application is built using preview-specific configuration.

6. Status Updated

   Deployment URL is posted back to the pull request.

2. Pull Request Updated

# New commits pushed
git push origin feature-branch

# Dokploy automatically:
1. Detects the update
2. Rebuilds the preview
3. Updates the deployment
4. Posts new status to PR

3. Pull Request Closed/Merged

1. Webhook Received

   Dokploy detects the PR was closed or merged.

2. Cleanup Initiated

   Preview deployment is automatically removed:

   - Stop container
   - Remove images
   - Delete domains
   - Clean up volumes (optional)
   
3. Resources Released

   Preview slot becomes available for new PRs.

Preview Limits

Control resource usage by setting a preview limit:

Preview Limit: 3

Active Previews:
✅ PR #123 - feature-auth
✅ PR #124 - bugfix-api
✅ PR #125 - new-ui

New PR #126:
❌ Skipped (limit reached)

When PR #123 closes:
✅ PR #126 can now deploy

When the limit is reached, oldest previews are not automatically removed. Close PRs to free up slots.

Managing Preview Deployments

Viewing Previews

Access all active previews in your application:

1. Navigate to “Preview Deployments” tab
2. View list of active previews with:
   • PR number and title
   • Branch name
   • Preview URL
   • Deployment status
   • Created date

Manual Redeployment

Redeploy a preview without pushing new commits:

UI

1. Open preview deployment
2. Click "Redeploy"
3. Monitor build logs

Manual Deletion

Remove a preview before the PR closes:

1. Open preview deployments list
2. Click delete icon next to preview
3. Confirm deletion

Deleting a preview doesn’t close the PR. It only removes the deployment.

SSL/TLS Configuration

Enable HTTPS

Let's Encrypt

Automatically provision SSL certificates:

Preview HTTPS: Enabled
Certificate Type: Let's Encrypt

Requires valid wildcard DNS record and reachable server.

Custom Certificate

Use your own wildcard certificate:

Preview HTTPS: Enabled
Certificate Type: Custom
Certificate: <wildcard-cert>
Private Key: <private-key>

Disabled

Preview deployments use HTTP only:

http://feature-123.preview.myapp.com

Use Cases

Frontend Testing

Review UI changes before merging:

• Design updates
• New features
• Bug fixes
• Responsive layouts

Client Demos

Share working features with stakeholders:

• Preview new functionality
• Collect feedback
• Validate requirements

QA Testing

Test changes in isolation:

• Regression testing
• Cross-browser testing
• Integration testing

API Testing

Test backend changes:

• New endpoints
• Database migrations
• Third-party integrations

Best Practices

Set Reasonable Limits

Configure preview limits based on available resources:

# Small server (2GB RAM)
Preview Limit: 2-3

# Medium server (4GB RAM)
Preview Limit: 5-7

# Large server (8GB+ RAM)
Preview Limit: 10+

Use Watch Paths

Avoid unnecessary deployments:

# Only deploy when app code changes
/src/**
/public/**
package.json

# Don't deploy for documentation changes
# /docs/** - not included
# README.md - not included

Enable Collaborator Restrictions

Always require collaborator permissions for security:

Require Collaborator Permissions: true ✅

Use Preview-Specific Variables

Isolate preview environments:

# Use separate databases
DATABASE_URL=postgresql://preview_${PR_NUMBER}

# Disable external services
ENABLE_EMAIL=false
ENABLE_ANALYTICS=false

# Use test credentials
STRIPE_KEY=${STRIPE_TEST_KEY}

Set Expiration Policies

Regularly clean up old previews:

# Close stale PRs
# Delete inactive previews
# Monitor resource usage

Troubleshooting

Preview Not Created

1. Check Collaborator Status

   If “Require Collaborator Permissions” is enabled:

   ✓ PR author must have write access
   ✓ Check repository permissions
   ✓ Verify organization membership
   
2. Verify Watch Paths

   If watch paths are configured:

   # PR must modify matching files
   git diff --name-only origin/main...feature-branch
   
3. Check Preview Limit

   Active Previews: 3/3 (limit reached)
   → Close a PR to free up a slot
   
4. Review Webhook Logs

   Check webhook delivery in your Git provider:

   Recent Deliveries → View Response
   

SSL Certificate Issues

# Verify DNS
dig *.preview.myapp.com

# Verify wildcard points to server
*.preview.myapp.com. → 1.2.3.4

# Check Let's Encrypt rate limits
# https://letsencrypt.org/docs/rate-limits/

Preview URL Not Accessible

1. Check Deployment Status

   Status: done ✅
   Status: error ❌ (check logs)
   
2. Verify Port Configuration

   Preview Port: 3000
   Application Port: 3000
   → Must match
   
3. Check Traefik Routing

   # View Traefik logs
   docker logs dokploy-traefik
   

Next Steps

Rollbacks

Learn how to rollback failed deployments

Environment Variables

Configure environment-specific variables