Skip to main content
Applications are containerized services that you deploy and run on Dokploy. They can be web applications, APIs, microservices, or any other software that can run in a Docker container.

What is an Application?

An application in Dokploy is a deployable service that runs as a Docker container. Dokploy handles the entire deployment lifecycle including:
  • Building from source code or Docker images
  • Configuring runtime environment
  • Managing domains and routing
  • Monitoring and logging
  • Automatic deployments from Git

Multiple Sources

Deploy from GitHub, GitLab, Bitbucket, Gitea, custom Git, Docker images, or by uploading files.

Build Methods

Support for Dockerfile, Nixpacks, Heroku buildpacks, Paketo buildpacks, and static sites.

Auto Deploy

Automatically deploy when you push code to your repository.

Preview Deployments

Create temporary deployments for pull requests to test changes before merging.

Application Lifecycle

Applications in Dokploy go through several stages:

Application Status

  • idle: Application is created but not deployed or has been stopped
  • running: Build or deployment is in progress
  • done: Application is successfully deployed and running
  • error: Deployment failed or application crashed

Source Types

Dokploy supports multiple ways to deploy your applications:

Git Providers

Connect to GitHub repositories using OAuth or GitHub Apps. Supports:
  • Automatic deployments on push or pull request
  • Submodule support
  • Branch protection
  • Preview deployments for pull requests

Docker Images

Deploy pre-built Docker images from:
  • Docker Hub
  • GitHub Container Registry (GHCR)
  • Private registries
  • Self-hosted registries

File Upload (Drop)

Upload a ZIP file containing your application code and deploy it directly:
// The drop deployment endpoint accepts a FormData with:
// - zip: The ZIP file containing your code
// - applicationId: Target application ID
// - dropBuildPath: Optional custom build path

Build Types

Dokploy supports multiple build strategies:

Dockerfile

Use an existing Dockerfile in your repository:
dockerfile
string
default:"Dockerfile"
Path to your Dockerfile relative to the build context
dockerContextPath
string
default:"."
Docker build context path
dockerBuildStage
string
Specific build stage to target in multi-stage builds

Nixpacks

Automatic detection and building using Nixpacks. No configuration needed for many common frameworks.

Buildpacks

Use Heroku’s official buildpacks for automatic detection and building.
herokuVersion
string
Specific Heroku stack version (e.g., heroku-22)

Static Sites

Deploy static websites with automatic web server configuration:
publishDirectory
string
default:"dist"
Directory containing the built static files
isStaticSpa
boolean
default:false
Enable single-page application routing (redirects all routes to index.html)

Configuration

Environment Variables

Manage your application’s environment variables through the UI or API:
# Format: KEY=value (one per line)
NODE_ENV=production
API_URL=https://api.example.com
DATABASE_URL=postgresql://user:pass@host:5432/db
Environment variables are inherited from the environment and project levels, with application-level variables taking precedence.

Build Arguments

Pass arguments to your Docker build:
NODE_VERSION=18
BUILD_ENV=production

Build Secrets

Securely pass sensitive data during build time without exposing them in the final image:
NPM_TOKEN=your-token-here
PRIVATE_KEY=your-key-here
Build secrets are only available during the build process and are not included in the final Docker image or runtime environment.

Resource Management

Control resource allocation for your applications:
memoryReservation
string
Minimum memory guaranteed for the container (e.g., “512m”, “1g”)
memoryLimit
string
Maximum memory the container can use (e.g., “1g”, “2g”)
cpuReservation
string
Minimum CPU guaranteed (e.g., “0.5”, “1.0”)
cpuLimit
string
Maximum CPU the container can use (e.g., “1.0”, “2.0”)

Domains and Routing

Applications can have multiple domains configured for routing traffic. See Domains & Routing for detailed information.

Quick Example

// Add a domain to your application
{
  host: "myapp.example.com",
  port: 3000,
  path: "/",
  https: true,
  certificateType: "letsencrypt"
}

Deployments

Manual Deployment

Trigger a deployment manually through the UI or API:
// Deploy endpoint
POST /api/application.deploy
{
  applicationId: "app_123",
  title: "Manual deployment",
  description: "Deploying latest changes"
}

Automatic Deployment

Enable automatic deployments when code is pushed to your repository:
autoDeploy
boolean
default:true
Automatically deploy when changes are pushed to the configured branch
triggerType
enum
default:"push"
When to trigger deployments: push or pull_request

Watch Paths

Optimize deployments by only triggering when specific paths change:
watchPaths: [
  "src/**",
  "package.json",
  "Dockerfile"
]
Use watch paths to avoid unnecessary deployments when documentation or unrelated files change.

Preview Deployments

Create temporary deployments for pull requests to test changes before merging:
isPreviewDeploymentsActive
boolean
default:false
Enable preview deployments for pull requests
previewLimit
integer
default:3
Maximum number of concurrent preview deployments
previewRequireCollaboratorPermissions
boolean
default:true
Require repository collaborator permissions to create preview deployments (security measure)

Preview Configuration

Preview deployments can have separate configuration:
  • previewEnv: Environment variables specific to preview deployments
  • previewBuildArgs: Build arguments for preview builds
  • previewWildcard: Domain pattern for preview deployments (e.g., *.preview.example.com)
  • previewPort: Port for preview applications
  • previewPath: Base path for preview routing

Advanced Features

Ports

Expose additional ports from your application:
{
  publishedPort: 8080,      // Port on the host
  targetPort: 8080,         // Port in the container
  protocol: "tcp"           // tcp or udp
}

Mounts

Persist data or inject configuration files:
{
  type: "volume",
  volumeName: "app-data",
  mountPath: "/app/data"
}

Redirects

Configure URL redirects for your application:
{
  regex: "^/old-path/(.*)",
  replacement: "/new-path/$1",
  permanent: true  // 301 vs 302 redirect
}

Security

Add HTTP basic authentication to your application:
{
  username: "admin",
  password: "secure-password"
}
Basic authentication is applied at the reverse proxy level. Use it for simple protection, but consider implementing proper authentication in your application for production use.

Database Schema

Applications are stored with the following structure:
interface Application {
  applicationId: string;
  name: string;
  appName: string;              // Unique internal name
  description?: string;
  environmentId: string;
  sourceType: "github" | "gitlab" | "bitbucket" | "gitea" | "git" | "docker" | "drop";
  buildType: "dockerfile" | "nixpacks" | "heroku_buildpacks" | "paketo_buildpacks" | "static" | "railpack";
  applicationStatus: "idle" | "running" | "done" | "error" | "restarting";
  
  // Build configuration
  env?: string;
  buildArgs?: string;
  buildSecrets?: string;
  command?: string;
  dockerfile?: string;
  dockerImage?: string;
  
  // Resources
  memoryReservation?: string;
  memoryLimit?: string;
  cpuReservation?: string;
  cpuLimit?: string;
  
  // Git configuration
  repository?: string;
  owner?: string;
  branch?: string;
  buildPath?: string;
  autoDeploy: boolean;
  
  createdAt: string;
}

Monitoring & Logs

Deployment Logs

View real-time logs during deployment:
  • Build output
  • Error messages
  • Deployment status

Runtime Logs

Access container logs after deployment:
  • stdout and stderr output
  • Historical logs
  • Real-time streaming

Resource Metrics

Monitor your application’s resource usage:
  • CPU usage
  • Memory consumption
  • Network traffic

Best Practices

Implement health check endpoints in your application to ensure Dokploy can properly monitor its status.
Always configure memory and CPU limits to prevent applications from consuming excessive resources.
Only enable automatic deployments for branches you trust. Consider using preview deployments for testing changes.
Use build secrets for build-time sensitive data and environment variables for runtime configuration.
Configure watch paths to avoid unnecessary deployments when unrelated files change.

Next Steps

Domains & Routing

Learn how to configure domains and routing for your applications

Databases

Add databases to your applications

Build docs developers (and LLMs) love