Deploying Applications

Learn how to deploy applications on Dokploy using various build methods and source providers

Dokploy provides flexible deployment options for applications built with Node.js, Python, Go, PHP, Ruby, and other languages. Applications can be deployed from Git repositories, Docker images, or uploaded code.

Supported Source Types

Dokploy supports multiple source types for deploying applications:

GitHub

Deploy applications from GitHub repositories with automatic webhook integration.

Configuration

1. Connect your GitHub account in Dokploy settings
2. Select repository, branch, and build path
3. Configure trigger type:
   • Push: Deploy on every push to the branch
   • Tag: Deploy only when tags are created

Watch Paths

Configure specific paths to monitor for changes. Deployments only trigger when files in these paths are modified.

# Example watch paths
/apps/frontend/**
/packages/shared/**

If no watch paths are configured, all file changes trigger deployments.

GitLab

Deploy from GitLab repositories (both cloud and self-hosted instances).

Configuration

1. Add GitLab provider with access token
2. Select project, branch, and build path
3. Configure namespace and project ID

Dokploy supports GitLab self-hosted instances. Configure the custom URL in provider settings.

Bitbucket

Deploy applications from Bitbucket Cloud repositories.

Configuration

1. Connect Bitbucket with OAuth
2. Select repository, workspace, and branch
3. Set build path for monorepo support

Gitea

Deploy from Gitea self-hosted Git repositories.

Configuration

1. Configure Gitea instance URL and token
2. Select repository and branch
3. Set build path if needed

Custom Git

Deploy from any Git repository using SSH or HTTPS.

Configuration

1. Provide Git repository URL
2. Upload SSH key if using SSH authentication
3. Configure branch and build path

# Example SSH URL
[e-mail]:user/repo.git

# Example HTTPS URL
https://github.com/user/repo.git

Docker Image

Deploy pre-built Docker images from public or private registries.

Configuration

1. Specify Docker image name and tag
2. Configure registry credentials (for private images)
3. Set registry URL if using custom registry

# Examples
nginx:latest
registry.example.com/myapp:v1.0.0
ghcr.io/organization/image:tag

Drop

Upload and deploy code directly from your local machine.

Usage

1. Zip your application code
2. Upload via the Dokploy UI
3. Configure build path within the uploaded archive

Drop deployments are ideal for testing but not recommended for production. Use Git providers for better version control.

Build Methods

Dokploy supports multiple build methods to accommodate different application types:

Nixpacks

Automatic detection and building of applications (default method).

Dockerfile

Build using your custom Dockerfile with full control.

Heroku Buildpacks

Use Heroku-compatible buildpacks for deployment.

Paketo Buildpacks

Cloud-native buildpacks following CNCF standards.

Static

Optimized for static sites and SPAs.

Railpack

Specialized buildpack for Rails applications.

Nixpacks (Recommended)

Nixpacks automatically detects your application type and generates an optimized build plan.

1. Automatic Detection

   Nixpacks analyzes your repository and detects:

   • Node.js (package.json)
   • Python (requirements.txt, Pipfile, pyproject.toml)
   • Go (go.mod)
   • Ruby (Gemfile)
   • PHP (composer.json)
   • Rust (Cargo.toml)
   • And many more…
2. Build Configuration

   No configuration needed for most applications. Nixpacks handles:

   • Dependency installation
   • Build commands
   • Start commands
   • Runtime environment
3. Custom Configuration

   Override defaults with a nixpacks.toml file in your repository:

   [phases.setup]
   nixPkgs = ['nodejs-18_x', 'python3']
   
   [phases.install]
   cmds = ['npm install']
   
   [phases.build]
   cmds = ['npm run build']
   
   [start]
   cmd = 'npm start'
   

Dockerfile

Use your own Dockerfile for complete control over the build process.

1. Configure Dockerfile

   Specify the Dockerfile path (relative to build path):

   Dockerfile
   docker/Dockerfile.production
   .docker/app.dockerfile
   
2. Docker Context Path

   Set the build context directory if your Dockerfile requires files from a parent directory:

   Build Path: /apps/api
   Context Path: / (to access workspace root)
   
3. Build Stage (Optional)

   Specify a target build stage for multi-stage Dockerfiles:

   FROM node:18 AS builder
   # Build stage
   
   FROM node:18-alpine AS production
   # Production stage
   

   Set production as the build stage to use only that stage.

Heroku Buildpacks

Deploy using Heroku-compatible buildpacks with version selection.

Supported Heroku versions: 20, 22, 24 (default)

# Dokploy automatically uses:
heroku/builder:24

Static Sites

Optimized deployment for static sites and Single Page Applications (SPAs).

1. Configure Build

   Set the publish directory where your built static files are located:

   dist
   build
   public
   out
   
2. SPA Mode

   Enable “Static SPA” option to:

   • Handle client-side routing
   • Redirect all 404s to index.html
   • Serve with optimized Nginx configuration

Railpack

Specialized buildpack for Ruby on Rails applications.

# Configuration
Railpack Version: 0.15.4 (default)

Build Configuration

Build Arguments

Pass build-time variables to your Docker build:

# Format: KEY=value (one per line)
NODE_ENV=production
API_VERSION=1.0.0
BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')

Build arguments are available during the build process but not in the running container. Use environment variables for runtime configuration.

Build Secrets

Securely pass sensitive information during build without including in the final image:

# Format: KEY=value (one per line)
NPM_TOKEN=npm_abc123xyz
GITHUB_TOKEN=ghp_xyz789abc

Build secrets are NOT persisted in the Docker image layers, making them ideal for credentials needed during build.

Git Submodules

Enable submodule support for repositories with Git submodules:

# Dokploy executes:
git clone --recurse-submodules --depth 1 <repository>

Ensure your Git provider credentials have access to all submodule repositories.

Resource Limits

Configure CPU and memory limits for your application:

Memory

# Memory Reservation (soft limit)
512m
1g
2048m

# Memory Limit (hard limit)
1g
2g
4096m

Memory reservation guarantees available memory. Memory limit is the maximum allowed.

CPU

# CPU Reservation (soft limit)
0.25  # 25% of one CPU core
0.5   # 50% of one CPU core
1     # 1 full CPU core

# CPU Limit (hard limit)
1     # 1 full CPU core
2     # 2 full CPU cores

CPU values are in cores. 0.5 = half a CPU core, 1 = one full CPU core.

Advanced Configuration

Custom Commands

Override the default container start command:

# Node.js example
node --max-old-space-size=4096 dist/index.js

# Python example
gunicorn --workers 4 --bind 0.0.0.0:8000 app:app

# Go example
./app --port 8080 --env production

Command Arguments

Pass arguments to the container command:

[
  "--port",
  "8080",
  "--workers",
  "4"
]

Replicas

Set the number of container instances to run:

1 (default)
3 (high availability)
5 (load distribution)

Multiple replicas require proper application design (stateless, session management, etc.).

Deployment Workflow

1. Create Application

   1. Navigate to your project
   2. Click “Add Service” → “Application”
   3. Enter application name and description
2. Configure Source

   1. Select source type (GitHub, GitLab, etc.)
   2. Choose repository and branch
   3. Set build path if using monorepo
3. Select Build Method

   1. Choose build type (Nixpacks, Dockerfile, etc.)
   2. Configure build-specific options
   3. Set environment variables
4. Deploy

   Click “Deploy” to start the build and deployment process.

   Monitor real-time logs during:

   • Source code cloning
   • Dependency installation
   • Application building
   • Image creation
   • Container startup

Application Status

Dokploy tracks your application through these states:

• idle: Application created but not deployed
• running: Deployment in progress
• done: Application deployed and running successfully
• error: Deployment failed (check logs for details)

Cleaning Cache

Force a clean build by enabling “Clean Cache” option:

# Dokploy executes:
docker build --no-cache ...

Clean cache rebuilds from scratch, which takes longer but resolves caching issues.

Next Steps

Environment Variables

Configure runtime environment variables

Preview Deployments

Set up automatic preview deployments

Rollbacks

Learn how to rollback deployments

Docker Compose

Deploy multi-container applications