Skip to main content
Dokploy is a self-hosted PaaS alternative to Heroku/Netlify. better-openclaw can deploy generated stacks directly to your Dokploy instance via the CLI or web UI.

​
Prerequisites

  • A running Dokploy instance (v0.5.0+)
  • Dokploy API token
  • Generated stack with docker-compose.yml and .env

​
Setup Dokploy

If you don’t have Dokploy installed, follow the official installation guide: 
curl -sSL https://dokploy.com/install.sh | sh
Access the dashboard at http://your-server-ip:3000.

​
Generate an API token

1

Open Dokploy dashboard

Navigate to your Dokploy instance dashboard.
2

Go to Settings

Click on Settings in the sidebar, then select Profile.
3

Create API token

Under API/CLI, click Generate Token.Copy the token immediately — it won’t be shown again.

​
Deploy via CLI

​
Interactive mode

Run the deploy command in your generated stack directory: 
cd my-openclaw-stack
npx create-better-openclaw deploy
The wizard will prompt for:
  1. Platform: Select Dokploy
  2. Instance URL: Your Dokploy instance (e.g., https://dokploy.example.com)
  3. API key: Paste the token from above
The CLI will:
  1. Test the connection
  2. Create a Dokploy project
  3. Create a compose stack
  4. Push environment variables
  5. Trigger the deployment

​
Non-interactive mode

For CI/CD pipelines, provide all flags: 
npx create-better-openclaw deploy \
  --provider dokploy \
  --instance-url https://dokploy.example.com \
  --api-key YOUR_API_TOKEN \
  --dir ./my-openclaw-stack
Add --json for machine-readable output: 
npx create-better-openclaw deploy \
  --provider dokploy \
  --instance-url https://dokploy.example.com \
  --api-key YOUR_API_TOKEN \
  --dir ./my-openclaw-stack \
  --json

​
Deploy via Web UI

1

Generate stack in Web UI

Open the better-openclaw web UI at http://localhost:3654.Select services, proxy, and configuration options.
2

Click 'Deploy'

After generating the stack, click the Deploy to PaaS button.
3

Configure deployment

Select Dokploy as the provider.Enter:
  • Instance URL: https://dokploy.example.com
  • API Key: Your Dokploy token
4

Deploy

Click Deploy. The UI will show real-time progress for each step.When complete, a link to the Dokploy dashboard will be displayed.

​
Deployment workflow

The deployer follows these steps:
1

Create project

Creates a new Dokploy project with the stack name.API endpoint: POST /api/project.create
2

Create compose stack

Creates a Docker Compose stack inside the project’s default environment.API endpoint: POST /api/compose.createUploads the generated docker-compose.yml.
3

Set environment variables

Pushes all variables from .env to the compose stack.API endpoint: POST /api/compose.update
4

Trigger deployment

Starts the deployment process.API endpoint: POST /api/compose.deployDokploy will:
  • Pull Docker images
  • Create volumes and networks
  • Start services with health checks

​
Monitoring deployment

​
CLI output

The CLI displays step-by-step progress: 
Deploying to Dokploy...
  Instance: https://dokploy.example.com
  Project:  my-openclaw-stack

Testing connection...
Connection OK

  done  Create project (Project ID: prj_abc123)
  done  Create compose stack (Compose ID: cmp_def456)
  done  Set environment variables
  done  Trigger deployment

Deployed successfully!
  Dashboard: https://dokploy.example.com/dashboard/project/prj_abc123

​
Dokploy dashboard

Open the dashboard URL to:
  • View deployment logs
  • Monitor service health
  • Manage environment variables
  • Configure domains and SSL

​
Managing deployed stacks

​
Update environment variables

1

Edit .env locally

Update your local .env file with new values.
2

Redeploy

Run the deploy command again:
npx create-better-openclaw deploy
The deployer will update variables and redeploy.
Alternatively, edit variables directly in the Dokploy dashboard:
  1. Navigate to Project > Compose
  2. Click Environment Variables
  3. Edit values and click Save
  4. Click Redeploy

​
Scale services

Scale services in the Dokploy dashboard:
  1. Navigate to Project > Compose
  2. Click on a service
  3. Adjust Replicas
  4. Click Save and Redeploy

​
View logs

Stream logs for a service:
  1. Navigate to Project > Compose
  2. Click on a service
  3. Click Logs tab
  4. Enable Follow for live streaming

​
Redeploy stack

Trigger a redeployment:
  1. Navigate to Project > Compose
  2. Click Deploy
  3. Optionally add a deployment title/description

​
CI/CD integration

​
GitHub Actions

name: Deploy to Dokploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate stack
        run: |
          npx create-better-openclaw@latest \
            --preset researcher \
            --yes \
            --output ./stack

      - name: Deploy to Dokploy
        run: |
          npx create-better-openclaw deploy \
            --provider dokploy \
            --instance-url ${{ secrets.DOKPLOY_URL }} \
            --api-key ${{ secrets.DOKPLOY_API_KEY }} \
            --dir ./stack \
            --json

​
GitLab CI

deploy:
  stage: deploy
  script:
    - npx create-better-openclaw@latest --preset researcher --yes --output ./stack
    - npx create-better-openclaw deploy --provider dokploy --instance-url $DOKPLOY_URL --api-key $DOKPLOY_API_KEY --dir ./stack --json
  only:
    - main

​
Troubleshooting

​
Connection failed

Error: Dokploy API 401: Unauthorized Solution: Verify your API token:
  1. Regenerate token in Dokploy dashboard
  2. Ensure token has full permissions
  3. Check for typos in the token

​
Project creation failed

Error: Dokploy API 409: Project already exists Solution: The project name is already in use. Either:
  • Delete the existing project in Dokploy
  • Regenerate the stack with a different name

​
Deployment timeout

Error: Services taking too long to start Solution:
  1. Check service logs in Dokploy dashboard
  2. Verify image availability (check Docker Hub/registry)
  3. Increase health check intervals in docker-compose.yml

​
Missing environment variables

Error: Services fail due to missing env vars Solution:
  1. Ensure .env file exists in the stack directory
  2. Check that all required variables are set
  3. Redeploy to push updated variables

​
API reference

The Dokploy deployer uses these API endpoints:
EndpointMethodPurpose
/api/project.allGETTest connection
/api/project.createPOSTCreate project
/api/project.oneGETGet project details
/api/compose.createPOSTCreate compose stack
/api/compose.updatePOSTUpdate environment variables
/api/compose.deployPOSTTrigger deployment
Authentication: x-api-key: <token> See the Dokploy API docs for full reference.

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us