First Deployment

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:

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.

Dokploy installed and running

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

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.

Navigate to dashboard

Create project

Click Create Project

Enter project details:

Name: my-web-app
Description: Production deployment of my web application

Click Create

Step 2: Set Up the Database

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

Create database

From your project dashboard:

Click the Databases tab
Click Create Database
Select PostgreSQL

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.

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.

Create and start

Click Create Database
Wait for the database to start (10-20 seconds)

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.

Public Repository
Private Repository
SSH Key

For public repositories:

Get repository URL

Copy your repository URL:

https://github.com/username/repository.git

Create application

Click the Applications tab
Click Create Application

Enter:

Name: my-web-app
Source Type: Git
Repository URL: https://github.com/username/repository.git
Branch: main

For private repositories, you need authentication:

Set up Git provider

First, connect your Git provider:

Navigate to Settings > Git Providers
Click Add Provider
Select your provider (GitHub, GitLab, or Bitbucket)
Click Authenticate
Grant necessary permissions

Create application with authentication

Click the Applications tab
Click Create Application

Enter:

Name: my-web-app
Source Type: Git
Git Provider: [Your authenticated provider]
Repository: username/repository
Branch: main

Use SSH keys for authentication:

Generate SSH key pair

On your local machine:

ssh-keygen -t ed25519 -C "dokploy@myserver" -f ~/.ssh/dokploy

Add public key to Git provider

GitHub:

Go to Settings > SSH and GPG keys
Click New SSH key
Paste contents of ~/.ssh/dokploy.pub

GitLab:

Go to Preferences > SSH Keys
Paste public key

Bitbucket:

Go to Personal settings > SSH keys
Add key

Add private key to Dokploy

Click Create Application
Select Git source
Click SSH Authentication
Paste contents of ~/.ssh/dokploy (private key)
Enter repository URL:
git@github.com:username/repository.git

Step 4: Configure Build Settings

Configure how Dokploy should build your application.

Select build method

Choose the appropriate build method:

Nixpacks (Auto-detect)
Dockerfile
Buildpacks

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.

For custom builds using your own Dockerfile:Configuration:

Build Method: Dockerfile
Dockerfile Path: ./Dockerfile
Build Context: .
Build Args: (optional)
  NODE_ENV: production

Example Dockerfile for Node.js:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Cloud Native Buildpacks for standardized builds:Configuration:

Build Method: Buildpacks
Builder: heroku/buildpacks:20

Buildpacks work well for applications following Heroku-style conventions.

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)

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.

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.

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]

DJANGO_SETTINGS_MODULE=myapp.settings.production
DEBUG=False
SECRET_KEY=[your-secret-key]
ALLOWED_HOSTS=app.example.com

APP_ENV=production
DB_HOST=myapp-db
DB_PORT=5432

RAILS_ENV=production
SECRET_KEY_BASE=[your-secret-key]
DATABASE_URL=postgresql://...

Use secret management (optional)

For sensitive values, consider using Dokploy’s built-in secrets:

Mark variables as Secret by clicking the lock icon
Secret values are encrypted and hidden in the UI
They’re only available to the running application

Step 6: Configure Domain and SSL

Set up a custom domain with automatic HTTPS.

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

Add domain in Dokploy

In your application settings:

Scroll to Domains
Click Add Domain
Enter your domain:
app.example.com
Enable Generate SSL Certificate
Click Add

Configure SSL/TLS

Dokploy uses Traefik with Let’s Encrypt for automatic SSL:

Navigate to Settings > Server
Enter your email for Let’s Encrypt notifications:
admin@example.com
Select certificate resolver: Let’s Encrypt
Save changes

SSL certificates are automatically issued, renewed, and managed. No manual intervention required.

Verify HTTPS

After deployment:

Wait 1-2 minutes for certificate issuance
Visit https://app.example.com
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!

Review configuration

Double-check all settings:

✅ Repository URL and branch
✅ Build method selected
✅ Environment variables configured
✅ Port specified
✅ Domain added (if using)

Start deployment

Click Create & Deploy (or Deploy if editing existing app)
The deployment process begins

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.

Verify deployment

Once complete, verify the application:

Check status shows Running with green indicator
Visit your domain: https://app.example.com
Or via IP: http://your-server-ip:3000

Step 8: Set Up Automated Deployments

Enable automatic deployments on Git push.

Enable auto-deploy

In your application settings:

Go to Settings > General
Enable Auto Deploy
Select trigger:
- On Push - Deploy on every push to the branch
- On Tag - Deploy only on new Git tags
- Manual - Require manual deployment trigger
Save changes

Configure webhook (GitHub/GitLab)

Set up a webhook for instant deployments:GitHub:

Go to your repository settings
Click Webhooks > Add webhook
Payload URL: https://your-dokploy-domain/api/webhooks/[app-id]
Content type: application/json
Select: Just the push event
Click Add webhook

GitLab:

Go to Settings > Webhooks
URL: https://your-dokploy-domain/api/webhooks/[app-id]
Trigger: Push events
Add webhook

Find your webhook URL in Dokploy under Settings > Webhooks.

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.

View application metrics

Monitor your application:

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

Configure notifications

Get alerted about deployment events:

Navigate to Settings > Notifications
Click Add Integration
Choose notification method:

Slack
Discord
Email
Telegram

Type: Slack
Webhook URL: https://hooks.slack.com/services/...
Channel: #deployments
Events:
  - Deployment Success
  - Deployment Failure
  - Application Down

Type: Discord
Webhook URL: https://discord.com/api/webhooks/...
Events:
  - Deployment Success
  - Deployment Failure

Type: Email
To: team@example.com
SMTP Settings: [Configure SMTP]
Events:
  - Deployment Failure
  - Application Down

Type: Telegram
Bot Token: [Your bot token]
Chat ID: [Your chat ID]
Events:
  - Deployment Success
  - Deployment Failure

Test notifications

Send a test notification:

Click Test next to your notification integration
Verify you receive the test message
Adjust settings as needed

Common Deployment Issues

Build fails - Dependencies not found

Symptoms: Build fails with “Module not found” or “Package not found”Solutions:

Ensure your lock file is committed (package-lock.json, yarn.lock, etc.)
Check Node.js version compatibility
Clear cache and rebuild:
- Go to Settings > Advanced
- Click Clear Build Cache
- Redeploy

Application won't start - Port issues

Symptoms: Container starts but immediately stops, or health check failsSolutions:

Verify the port in settings matches your application:

// Your app should use PORT from environment
const PORT = process.env.PORT || 3000;
app.listen(PORT);

Check application logs for startup errors
Ensure your start command is correct

Database connection fails

Symptoms: Application logs show “Connection refused” or “Cannot connect to database”Solutions:

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

Verify database is running:
- Go to Databases tab
- Check database status is Running
Check credentials match database configuration

SSL certificate not issued

Symptoms: HTTPS doesn’t work, or shows “Invalid certificate”Solutions:

Verify DNS is correctly configured:
dig app.example.com
Ensure ports 80 and 443 are open:
sudo ufw allow 80 sudo ufw allow 443
Check Let’s Encrypt rate limits (5 certificates per domain per week)
Wait 5-10 minutes after adding domain for initial certificate issuance

Out of memory errors

Symptoms: Application crashes with “JavaScript heap out of memory” or similarSolutions:

Increase memory limit:
- Go to Settings > Resources
- Increase Memory to 1GB or higher
Optimize your build:
- Use production builds: NODE_ENV=production
- Minimize dependencies in production
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.

Overview

Getting Started

Core Concepts

Deployments

Databases

Monitoring & Observability

Advanced Features

Configuration

CLI & Automation

Community & Support

First Deployment

Overview

What We’ll Deploy

Prerequisites

Step 1: Create a Project

Step 2: Set Up the Database

Step 3: Connect Your Git Repository

Step 4: Configure Build Settings

Step 5: Configure Environment Variables

Step 6: Configure Domain and SSL

Step 7: Deploy the Application

Step 8: Set Up Automated Deployments

Step 9: Configure Monitoring and Alerts

Common Deployment Issues

Best Practices

Use Environment Variables

Enable Health Checks

Configure Resource Limits

Set Up Backups

Monitor Logs

Use Staging Environment

Next Steps

Custom Domains

Database Backups

Docker Compose

Multi-Node Setup

CI/CD Integration

Monitoring

Summary

​Overview

​What We’ll Deploy

​Prerequisites

​Step 1: Create a Project

​Step 2: Set Up the Database

​Step 3: Connect Your Git Repository

​Step 4: Configure Build Settings

​Step 5: Configure Environment Variables

​Step 6: Configure Domain and SSL

​Step 7: Deploy the Application

​Step 8: Set Up Automated Deployments

​Step 9: Configure Monitoring and Alerts

​Common Deployment Issues

​Best Practices

Use Environment Variables

Enable Health Checks

Configure Resource Limits

Set Up Backups

Monitor Logs

Use Staging Environment

​Next Steps

Custom Domains

Database Backups

Docker Compose

Multi-Node Setup

CI/CD Integration

Monitoring

​Summary

Overview

What We’ll Deploy

Prerequisites

Step 1: Create a Project

Step 2: Set Up the Database

Step 3: Connect Your Git Repository

Step 4: Configure Build Settings

Step 5: Configure Environment Variables

Step 6: Configure Domain and SSL

Step 7: Deploy the Application

Step 8: Set Up Automated Deployments

Step 9: Configure Monitoring and Alerts

Common Deployment Issues

Best Practices

Next Steps

Summary