Having a preview deployment feature is one of the pros of using Dokploy. Not only does it reduce the hassle of doing PR reviews, but it also makes QA and working collaboratively much easier. In this guide, I will walk you through how to set up this preview deployment feature in Dokploy and believe me, it’s really easy. But first, we need to know the why.
So why use it?
If you're familiar with GitHub Flow, you’ll quickly see the benefit of having preview deployments. But even if you're coming from Git Flow, this feature can still be useful for your workflow.
In GitHub Flow, there are usually a lot of PRs waiting to be merged into main. With preview deployments, you don’t need to constantly switch branches to test changes. Each PR has its own live environment, so reviews by the stakeholders (both technical and non-technical) are faster and smoother. It also makes working with your team easier, since they can access the preview site, run tests, and even send it to the client. Most importantly, all changes stay isolated from the production site.
Now, you might be thinking:
"But we already have a dev site/branch for testing.”
That’s great - if you have a single feature being developed at the same time, and with very responsive stakeholders / reviewers. But when multiple features are being QA-end in a single environment, unrelated problems usually come up. It becomes hard to know which of the feature is causing which change, and reviewing them in isolation is basically impossible.
That’s when previews (or review apps as they’re called in Heroku) come to the rescue. With them, each pull request (and by extension feature or bug fix) gets a dedicated environment without the need to merge it into a shared branch (such as development). Plus, you can send that final preview to your client, allowing them to test one specific feature asynchronously.
Now that you know why preview deployments are so useful, let’s roll up our sleeves and set them up in Dokploy.
How to set up preview deployment
First things first, you need an application, and the service type should be “Application”. If you don’t already know how to deploy an app, you can follow this step-by-step tutorial to get started.
Once you have an application, select it, and navigate to the Preview Deployment tab. Click Configure, and you’ll see this form:
You can use a custom domain as long as you have a wildcard DNS record configured. If you haven’t done this before, you’ll need to set it up through your domain provider. The exact steps vary slightly depending on the provider, but the process is essentially the same. Here’s a guide on wildcard DNS setup to get you started.
If you’re fine with the default, you can leave it as-is because, by default, Dokploy uses traefik.me to generate dynamic domains for you, and it’s free.
So if my wildcard domain is like this:
*.devmystify.com
The preview deployment URLs will look like this:
preview-${appName}-${uniqueId}.devmystify.com
There are four fields you can configure: Wildcard Domain, Preview Path, Port, and Preview Limit.
In most cases, you can leave the defaults as they are. The important one is Port, which should match your app’s exposed port (for a Next.js app, this is usually 3000). Other fields, such as Preview Path (to restrict previews to certain routes) or Preview Limit (to control how many preview deployments can run, which affects resource usage), are optional depending on your needs.
Be sure to slide the “Enable Preview Deployment” switch to ON.
Once everything is set up, whenever you create a pull request against the main branch (or whichever branch you chose when deploying the app), Dokploy will automatically comment on the PR with a preview link.
You’ll also see the preview site in your Dokploy dashboard, where you can check build logs and application logs.
And that’s it! You can now go to the link and preview your feature.site. Another really cool thing is that when you close the PR, Dokploy automatically cleans up the preview site for you.
Note: It’s worth mentioning that dynamically generated domains can sometimes cause issues if you rely on environment variables for your base URL, especially when calling APIs. To handle this, check the request headers like
x-forwarded-hostandx-forwarded-protothat Traefik provides. This will help you work around any dynamic URL problems.
Preview deployments are one of those features that appear minor at first, but can make a big difference in your workflow. They cut down on context switching, improve collaboration, and let you share clean environments with clients without worrying about breaking your dev or production sites.
Thanks to Dokploy, setting them up is straightforward and quick (the only part that might take a little time is waiting for your wildcard DNS to propagate). Once you’ve tried it, you’ll probably wonder how you ever managed reviews without it.