Skip to main content

​
Overview

This guide walks through deploying a complete application to Dokploy, from connecting a Git repository to configuring domains and SSL. We’ll deploy a Node.js application, but the process is similar for other languages.
This tutorial assumes you’ve completed the Installation and reviewed the Quickstart guide.

​
What We’ll Deploy

In this tutorial, we’ll deploy a full-stack application with:
  • Frontend: React/Next.js application
  • Database: PostgreSQL database
  • Domain: Custom domain with automatic SSL
  • Monitoring: Real-time logs and metrics
By the end, you’ll have a production-ready deployment accessible via HTTPS.

​
Prerequisites

Before starting, ensure you have:
1

A Git repository

Your application code hosted on:
  • GitHub
  • GitLab
  • Bitbucket
  • Any Git-compatible service
Don’t have an app ready? Fork our example repository to follow along.
2

Dokploy installed and running

Access your Dokploy dashboard at http://your-server-ip:3000
3

Domain name (optional)

A domain pointed to your server’s IP address.If you don’t have a domain, you can still deploy and access via IP:PORT.

​
Step 1: Create a Project

Projects help organize related applications and databases.
1

Navigate to dashboard

Log in to your Dokploy dashboard.
2

Create project

  1. Click Create Project
  2. Enter project details: 
    Name: my-web-app
Description: Production deployment of my web application
  3. Click Create

​
Step 2: Set Up the Database

Most applications need a database. Let’s create a PostgreSQL database first.
1

Create database

From your project dashboard:
  1. Click the Databases tab
  2. Click Create Database
  3. Select PostgreSQL
2

Configure database

Enter the database configuration:
Name: myapp-db
Version: 16-alpine
Database Name: myapp_production
Username: myapp_user
Password: [Generate secure password]
Click the Generate button to create a secure random password.
3

Set resource limits

Configure resource constraints:
Memory Limit: 512MB
CPU Limit: 0.5
Start with conservative limits. You can adjust based on actual usage later.
4

Create and start

  1. Click Create Database
  2. Wait for the database to start (10-20 seconds)
  3. Copy the connection string: 
    postgresql://myapp_user:[password]@myapp-db:5432/myapp_production
Save the connection string securely. You’ll need it for the application configuration.

​
Step 3: Connect Your Git Repository

Now let’s connect your application repository.
For public repositories:
1

Get repository URL

Copy your repository URL:
https://github.com/username/repository.git
2

Create application

  1. Click the Applications tab
  2. Click Create Application
  3. Enter: 
    Name: my-web-app
Source Type: Git
Repository URL: https://github.com/username/repository.git
Branch: main

​
Step 4: Configure Build Settings

Configure how Dokploy should build your application.
1

Select build method

Choose the appropriate build method:
Recommended for most applications. Nixpacks automatically detects:
  • Node.js (package.json)
  • Python (requirements.txt, Pipfile)
  • Go (go.mod)
  • Ruby (Gemfile)
  • PHP (composer.json)
  • Rust (Cargo.toml)
Configuration:
Build Method: Nixpacks
Build Command: [Auto-detected]
Start Command: [Auto-detected]
Nixpacks will detect your build and start commands from package.json scripts or standard conventions.
2

Configure build settings

Set optional build configurations:
Build Path: . (root directory)
Install Command: npm install (or auto-detected)
Build Command: npm run build (or auto-detected)
Start Command: npm start (or auto-detected)
3

Set application port

Specify the port your application listens on:
Port: 3000
Ensure this matches the port your application actually uses. Common ports: 3000 (Node.js), 8080 (Go), 5000 (Python).

​
Step 5: Configure Environment Variables

Add environment variables needed by your application.
1

Add database connection

In the Environment Variables section:
DATABASE_URL=postgresql://myapp_user:[password]@myapp-db:5432/myapp_production
Use the internal Docker network hostname (e.g., myapp-db) instead of localhost or the server IP.
2

Add application-specific variables

Add any other required environment variables:
NODE_ENV=production
PORT=3000
API_URL=https://api.example.com
SECRET_KEY=[your-secret-key]
3

Use secret management (optional)

For sensitive values, consider using Dokploy’s built-in secrets:
  1. Mark variables as Secret by clicking the lock icon
  2. Secret values are encrypted and hidden in the UI
  3. They’re only available to the running application

​
Step 6: Configure Domain and SSL

Set up a custom domain with automatic HTTPS.
1

Point domain to server

First, configure your DNS:Add an A record:
Type: A
Name: @ (or subdomain like "app")
Value: [your-server-ip]
TTL: 3600
Wait for DNS propagation (5-30 minutes).
Verify DNS propagation: dig app.example.com or use dnschecker.org
2

Add domain in Dokploy

In your application settings:
  1. Scroll to Domains
  2. Click Add Domain
  3. Enter your domain: 
    app.example.com
  4. Enable Generate SSL Certificate
  5. Click Add
3

Configure SSL/TLS

Dokploy uses Traefik with Let’s Encrypt for automatic SSL:
  1. Navigate to Settings > Server
  2. Enter your email for Let’s Encrypt notifications: 
    [email protected]
  3. Select certificate resolver: Let’s Encrypt
  4. Save changes
SSL certificates are automatically issued, renewed, and managed. No manual intervention required.
4

Verify HTTPS

After deployment:
  1. Wait 1-2 minutes for certificate issuance
  2. Visit https://app.example.com
  3. Verify the padlock icon in the browser
If you see a certificate error, wait a few more minutes. Initial certificate issuance can take 2-5 minutes.

​
Step 7: Deploy the Application

Now we’re ready to deploy!
1

Review configuration

Double-check all settings:
  • ✅ Repository URL and branch
  • ✅ Build method selected
  • ✅ Environment variables configured
  • ✅ Port specified
  • ✅ Domain added (if using)
2

Start deployment

  1. Click Create & Deploy (or Deploy if editing existing app)
  2. The deployment process begins
3

Monitor build progress

Watch the real-time build logs:
[01] Cloning repository...
[02] ✓ Repository cloned successfully
[03] Detecting application type...
[04] ✓ Detected Node.js application
[05] Installing dependencies...
[06] ✓ Dependencies installed
[07] Running build command...
[08] ✓ Build completed successfully
[09] Creating Docker image...
[10] ✓ Image created: myapp:latest
[11] Starting container...
[12] ✓ Container started successfully
[13] Health check passed
[14] ✓ Deployment complete!
Build times vary based on application size and complexity. Typical builds take 2-5 minutes.
4

Verify deployment

Once complete, verify the application:
  1. Check status shows Running with green indicator
  2. Visit your domain: https://app.example.com
  3. Or via IP: http://your-server-ip:3000

​
Step 8: Set Up Automated Deployments

Enable automatic deployments on Git push.
1

Enable auto-deploy

In your application settings:
  1. Go to Settings > General
  2. Enable Auto Deploy
  3. Select trigger:
    • On Push - Deploy on every push to the branch
    • On Tag - Deploy only on new Git tags
    • Manual - Require manual deployment trigger
  4. Save changes
2

Configure webhook (GitHub/GitLab)

Set up a webhook for instant deployments:GitHub:
  1. Go to your repository settings
  2. Click Webhooks > Add webhook
  3. Payload URL: https://your-dokploy-domain/api/webhooks/[app-id]
  4. Content type: application/json
  5. Select: Just the push event
  6. Click Add webhook
GitLab:
  1. Go to Settings > Webhooks
  2. URL: https://your-dokploy-domain/api/webhooks/[app-id]
  3. Trigger: Push events
  4. Add webhook
Find your webhook URL in Dokploy under Settings > Webhooks.
3

Test automatic deployment

Make a code change and push:
git add .
git commit -m "Test auto-deploy"
git push origin main
Watch the deployment automatically trigger in Dokploy.

​
Step 9: Configure Monitoring and Alerts

Set up monitoring and notifications.
1

View application metrics

Monitor your application:
  1. Open your application in Dokploy
  2. Click Monitoring tab
  3. View real-time metrics:
    • CPU usage
    • Memory consumption
    • Network I/O
    • Request rates (if applicable)
2

Configure notifications

Get alerted about deployment events:
  1. Navigate to Settings > Notifications
  2. Click Add Integration
  3. Choose notification method:
Type: Slack
Webhook URL: https://hooks.slack.com/services/...
Channel: #deployments
Events:
  - Deployment Success
  - Deployment Failure
  - Application Down
3

Test notifications

Send a test notification:
  1. Click Test next to your notification integration
  2. Verify you receive the test message
  3. Adjust settings as needed

​
Common Deployment Issues

Symptoms: Build fails with “Module not found” or “Package not found”Solutions:
  1. Ensure your lock file is committed (package-lock.json, yarn.lock, etc.)
  2. Check Node.js version compatibility
  3. Clear cache and rebuild:
    • Go to Settings > Advanced
    • Click Clear Build Cache
    • Redeploy
Symptoms: Container starts but immediately stops, or health check failsSolutions:
  1. Verify the port in settings matches your application: 
    // Your app should use PORT from environment
const PORT = process.env.PORT || 3000;
app.listen(PORT);
  2. Check application logs for startup errors
  3. Ensure your start command is correct
Symptoms: Application logs show “Connection refused” or “Cannot connect to database”Solutions:
  1. Use internal Docker hostname, not localhost: 
    # Wrong
DATABASE_URL=postgresql://user:pass@localhost:5432/db

# Correct
DATABASE_URL=postgresql://user:pass@myapp-db:5432/db
  2. Verify database is running:
    • Go to Databases tab
    • Check database status is Running
  3. Check credentials match database configuration
Symptoms: HTTPS doesn’t work, or shows “Invalid certificate”Solutions:
  1. Verify DNS is correctly configured: 
    dig app.example.com
  2. Ensure ports 80 and 443 are open: 
    sudo ufw allow 80
sudo ufw allow 443
  3. Check Let’s Encrypt rate limits (5 certificates per domain per week)
  4. Wait 5-10 minutes after adding domain for initial certificate issuance
Symptoms: Application crashes with “JavaScript heap out of memory” or similarSolutions:
  1. Increase memory limit:
    • Go to Settings > Resources
    • Increase Memory to 1GB or higher
  2. Optimize your build:
    • Use production builds: NODE_ENV=production
    • Minimize dependencies in production
  3. Consider upgrading your server resources

​
Best Practices

Use Environment Variables

Never hardcode configuration:
  • Database URLs
  • API keys
  • Secret tokens
Always use environment variables.

Enable Health Checks

Add a health check endpoint:
app.get('/health', (req, res) => {
  res.status(200).send('OK');
});

Configure Resource Limits

Set appropriate limits:
  • Memory: Based on actual usage + 20% buffer
  • CPU: Start with 0.5, adjust as needed

Set Up Backups

Enable automatic database backups:
  • Daily backups minimum
  • Keep 7-30 days of backups
  • Test restoration regularly

Monitor Logs

Regularly check application logs:
  • Review error logs weekly
  • Set up alerts for critical errors
  • Use structured logging

Use Staging Environment

Create separate projects:
  • Production - Live application
  • Staging - Testing before production
  • Development - Active development

​
Next Steps

Your application is deployed! Now explore advanced features:

Custom Domains

Add multiple domains and configure advanced routing

Database Backups

Set up automated backups to S3 or other storage

Docker Compose

Deploy multi-container applications

Multi-Node Setup

Scale across multiple servers

CI/CD Integration

Advanced Git integration and workflows

Monitoring

Deep dive into monitoring and observability

​
Summary

You’ve successfully:
  • ✅ Created a project and database
  • ✅ Connected a Git repository
  • ✅ Configured build settings
  • ✅ Set up environment variables
  • ✅ Deployed with custom domain and SSL
  • ✅ Enabled automated deployments
  • ✅ Configured monitoring and alerts
Your application is now running in production on Dokploy!
Need help? Join our Discord community or check the troubleshooting guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us