Handling Deployments in Dokploy 2025: A Tutorial

Table of Contents

1. Introducttion
2. Primary Deployment Methods in Dokploy
3. Choosing the Right Deployment Method
4. Conclusion

Introducttion

Dokploy is a relatively new platform in the market. However, it is to be taken seriously given that it is open-source, free, and simple and that you can self-host it.

Dokploy supports multiple deployment methods to suit its users. The type you choose should be based on your requirements. The choice you make in the deployment methods impacts how you manage your application's deployment life pipeline. Selecting the right method ensures a seamless and efficient process and allows you to streamline the process.

Below, we will walk through the primary deployment methods provided by Dokploy, including their descriptions, processes, and considerations.

Primary Deployment Methods in Dokploy

There are 6 categories of deployment methods in Dokploy as of the writing of this article:

1. Application Deployment
2. Docker Compose Deployment
3. Auto Deployment
4. Database deployment
5. Template Deployment
6. AI Assistant Deployment

Let's go through each to understand them better clearly.

1. Application Deployment

Description

Application deployment is a simple method for deploying simple applications that require minimal configurations.

Source Providers:

Dokploy integrates with popular source control systems such as:

• GitHub
• GitLab
• Bitbucket
• Generic Git repositories

Build types

• Nixpacks: Automatically detects and builds applications.
• Railpack: An efficient and optimized successor of Nixpacks
• Dockerfile: Abuild type that gives you full control over the build environment using a Dockefile file.
• Buildpacks: Supports Heroku and Paketo build packs.
• Static: Serves static applications using optimized NGIX Dockerfile.

Process 1: Standard Application Deployment

1. Connect your repository: Link your application repository from GitHub, GitLab, or another Git source.
2. Select branch: Choose the branch from your repository you want to deploy.
3. Configure build and start commands: Define the commands that build and start your application. These are typically specified in the Dockerfile, Procfile, or similar configuration files.
4. Configure build path and publish directory:
   • Set the build path to define where Dokploy should look for the source code or binaries.
   • Specify the publish directory where Dokploy will output the built application.
5. Add environment variables: Navigate to the "Environments" tab and add any necessary environment variables that your app requires (e.g., DATABASE_URL, API_KEY).
6. Deploy the application: Once your settings are configured, initiate the deployment process.
7. Generate Domain and set port: Dokploy will generate a domain for your application and assign it to a specified port (e.g., 80 for HTTP or 443 for HTTPS).

Process 2: Docker Deployment

1. Connect your repository: Similar to the standard deployment, connect your repository.
2. Select branch: Choose the branch for deployment.
3. Configure build path: Set the path to the directory where your Dockerfile is located.
4. Select Dockerfile as Build Type: Specify Dockerfile as the build type.
5. Specify Dockerfile path: Enter the exact path to your Dockerfile.
6. Deploy the application: Deploy the application using the Dockerfile configuration.
7. Generate Domain and Set Port: Dokploy will generate a domain for your application and set up the necessary ports.

Considerations:

• Ideal for simple, single applications with minimal configuration.
• For more complex setups with multiple services, Docker Compose might be a better choice.

2. Docker Compose Deployment

Description:

Docker Compose comes into the picture when your application requires working with multiple services or has more complex configurations. This method provides greater flexibility and control.

Process:

1. Create a New Project in Dokploy:

• Log in to your Dokploy dashboard.​
• Create a new project and select Docker Compose as the deployment method.​

1. Fork the Example Repository:

• Fork the Dokploy/docker-compose-test repository on GitHub.​
• Clone the repository to your local machine:

git clone https://github.com/your-username/docker-compose-test.git

• Navigate to the project directory:

cd docker-compose-test

1. Configure the Docker Compose File:

• Open the docker-compose.yml file in your preferred editor.​
• Modify the file to include the Dokploy network and Traefik labels for routing.
• Ensure the file resembles the following structure:

version: "3"
services:
  next-app:
    build:
      context: ./next-app
      dockerfile: prod.Dockerfile
      args:
        ENV_VARIABLE: ${ENV_VARIABLE}
        NEXT_PUBLIC_ENV_VARIABLE: ${NEXT_PUBLIC_ENV_VARIABLE}
    restart: always
    ports:
      - 3000
    networks:
      - dokploy-network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.next-app.rule=Host(`your-domain.com`)"
      - "traefik.http.routers.next-app.entrypoints=websecure"
      - "traefik.http.routers.next-app.tls.certResolver=letsencrypt"
      - "traefik.http.services.next-app.loadbalancer.server.port=3000"
networks:
  dokploy-network:
    external: true

• Replace your-domain.com with your desired domain name.

1. Push Changes to Your Repository:

• Commit your changes:

git add docker-compose.yml
git commit -m "Configure Docker Compose for Dokploy deployment"

• Push the changes to your GitHub repository:

git push origin main

1. Set Up the Deployment in Dokploy:
   • In the Dokploy dashboard, configure the following settings:​
     • Provider Type: Select GitHub or Git based on your repository.
     • Repository: Choose your forked repository.
     • Branch: Set to main.
     • Compose Path: Enter ./docker-compose.yml.
2. Deploy the application:
   • Click Deploy in the Dokploy dashboard.​
   • Wait for the deployment to complete.​
   • Allow Traefik approximately 10 seconds to generate SSL certificates.
3. Access Your Application:

• Once deployed, access your application at https://your-domain.com.​

Considerations:

• Best for applications that involve multiple interconnected services, such as databases, web servers, or background jobs.
• Offers granular control over deployment and service orchestration.

3. Auto Deployments

Description:

Auto Deployments automate the deployment process by triggering builds whenever there is a change in your source repository. This method is ideal for CI/CD (continuous integration/continuous deployment) workflows.

Auto-deployment Methods:

• Webhooks: Integrates with GitHub, GitLab, Bitbucket, Gitea, and DockerHub to automatically trigger deployments when code changes are pushed.
• Dokploy API: Enables programmatic deployment triggers, making it suitable for integrating with CI/CD pipelines.

Process:

1. Generate an API Token:

• Log in to your Dokploy account.​
• Navigate to your profile settings.​
• Create a new API token and copy it; you'll need it for authentication.​

1. Retrieve Your Application ID:

• Use the following curl command to list all projects and services:​

curl -X 'GET' \
  'https://your-dokploy-domain/api/project.all' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-api-token>'

• Replace your-dokploy-domain with your Dokploy domain and <your-api-token> with the token you generated.​
• Identify the applicationId for the application you wish to deploy from the response.

1. Trigger a Deployment:

• Use the following curl command to trigger a deployment:​

curl -X 'POST' \
  'https://your-dokploy-domain/api/application.deploy' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-token>' \
  -d '{
  "applicationId": "<your-application-id>"
}'

• Replace <your-api-token> with your API token and <your-application-id> with the applicationId you retrieved earlier.​

Considerations:

• Reduces manual intervention, ensuring that your application is always up-to-date with the latest code.
• Essential for modern CI/CD workflows.

Database Deployment

Dokploy allows you to provision and manage a database of your choice. You can select from a range of available databases such as PostgreSQL, MongoDB, MySQL, MariaDB, Redis, and others. This method is ideal for apps that require a dedicated database instance for storage.

Process to Deploy a Database in Dokploy

1. Create a New Project in Dokploy
   • Begin by logging into Dokploy.
   • Navigate to the Projects section and create a new project by providing a project name.
2. Create a New Database Service
   • Inside the newly created project, click on Create New Service.
   • Select Database as the service type.
   • From the available database options, choose the database of your choice (e.g., PostgreSQL, MongoDB, MySQL, etc.).
3. Configure Database Details:
   • Fill out the necessary connection details, including:
     • Service Name: A name for the service.
     • Server: The server where the database will be hosted.
     • App Name: The name of the application associated with the database.
     • Description: A brief description of the database or its purpose.
     • Database Name: The name of the database to be created.
     • Database User: The username for accessing the database.
     • Database Password: The password associated with the database user.
     • Docker Image: The Docker image of the chosen database (e.g., postgres:16, mongodb:latest).
4. Configure Environment Variables (Optional):
   • Navigate to the Environment tab and set the key-value pairs required for your database. These might include variables like DATABASE_URL, DB_HOST, DB_PORT, DB_USER, and DB_PASSWORD.
5. Create the Service:
   • Once you've configured the details, click on Create Service to deploy the service.
6. Monitor the Service and View Logs:
   • Once the database is up, you can use the Monitoring tab to track how it is using resources.
   • Alternatively, check the Logs tab for any issues or to view the database activity.
7. Configure Backups:
   • Once the database is running and the logs are clear, you should consider setting up backups to ensure data safety. For this, go to the Backups tab.
   • Note that you will first need to configure an S3 destination where the backups will be stored.
   • After setting up the S3 destination, you can connect it to the database and schedule regular backups.

Considerations:

• Database Availability: By deploying the database as a service, you ensure that it is isolated and can scale independently from the application.
• Security: Ensure that sensitive information, such as credentials, is stored securely as environment variables.
• Backup and Recovery: Set up regular backups to avoid information loss.

Template Deployment

Template deployment allows you to deploy applications from predefined templates quickly. This is ideal for users who want quick deployments of applications with common configurations.

Process to Deploy Using a Template in Dokploy

1. Create a New Project in Dokploy
   • Log in to Dokploy with your account.
   • Navigate to the Projects section and create a new project by specifying the project name.
2. Create a New Service
   • Inside the newly created project, create a service with the service type specified as Template.
   • This will open a window to select templates.
3. Select the Preferred Template
   • Browse through the available templates and choose the one that best fits your needs.
   • Dokploy will automatically create a service based on the selected template.
4. Modify and Configure the Template
   • You can view and modify the configuration of the template to suit your specific requirements.
5. Create the Service
   • Once you're satisfied with the configuration, click Create Service to deploy the template-based service.
6. Deploy the Service
   • Finally, click Deploy to launch the service.

Considerations:

• Predefined Configurations: Templates provide a predefined structure, which saves time. However, you may need to modify the configurations to suit your needs.
• Speed of Deployment: Template deployment is ideal for quickly getting the app up and running.
• Customization: Some templates may need additional customization to align with your specific needs.
• Template Limitations: Templates are convenient, but they may not cover all use cases. If you have very specific needs, templates might not be the best deployment type for you.
• Resource Management: Even though templates provide a quick deployment, always ensure that the resources allocated in the template are sufficient for your application.

AI Assistant Deployment

AI Assistant deployment utilizes the power of artificial intelligence to automate and streamline your deployments. Before deploying, you must set up and configure its settings in the AI Settings.

Considerations

• Review before deploying: Always review AI-assisted work before using it.

Choosing the Right Deployment Method

• For single, simple applications, use application deployment for easy setup and management.
• For complex applications with multiple services, choose Docker Compose deployment to manage interconnected services effectively.
• For Continuous Integration/Continuous Deployment (CI/CD): Implement Auto Deployments to automate deployments in response to code changes.
• For applications that require a dedicated database, use Database deployment to deploy the database service.
• For quick deployments with minimal predefined configurations, use Template deployment.
• If looking to automate the deployment process using artificial intelligence use AI Assistant Deployment.

By selecting the appropriate deployment method for your application, you can ensure a streamlined process and efficient management of your application within the Dokploy platform.

Conclusion

Dokploy offers a variety of deployment options suited to different types of applications. Whether you're deploying a single app or managing a complex multi-service system, understanding and selecting the right deployment method is key to maintaining a smooth, automated workflow. Our article helps you achieve this by offering clear guidance on the available deployment methods, processes, and considerations. This helps you make an informed choice that best suits your needs. Happy deployments!

Frequently Asked Questions