Deploy your Nx projects to Dokku with ease using this plugin. With a simple configuration, you can deploy your application directly to your Dokku server via nx deploy

Contents

• 📦 Installation
• 🚀 Usage
• 🛠️ Troubleshooting
• 🤝 Support

📦 Installation

Prerequisites

Make sure you have the following:

• An existing Nx workspace
• A buildable project set up within this workspace

Step 1: Install the plugin

NPM:

npm install nx-dokku --save-dev

Yarn:

yarn add nx-dokku --dev

Step 2: Choose an executor

Add a new target called deploy in your project's project.json file and configure one of the following executors:

| | Executor | Description | | --- | ------------- | ------------------------------------------- | | a | deploy-dist | Deploy your pre-built application to Dokku | | b | deploy-src | Let Dokku build and deploy your application |

Step 3a: Configure executor deploy-dist

Deploy your pre-built application by pushing the distributable directory to Dokku. To achieve this without tracking build files in your main repository, a local repository will be generated within the distributable directory.

Options

| Option | Description | Default | | ------------- | ------------------------------------------------ | -------- | | host | The host of your Dokku server | None | | app | The name of your Dokku application | None | | path | The path to the distributable directory | None | | dokkuBranch | The deploy branch to push to on the Dokku server | master |

{
  "deploy": {
    "executor": "nx-dokku:deploy-dist",
    "options": {
      "host": "server.example.com",
      "app": "my-dokku-app",
      "path": "dist/apps/my-app"
    }
  }
}

Step 3b: Configure executor deploy-src

Let Dokku build and serve the application after deploying the project source.

Note: It's not recommended to use this executor for JS/TS projects due to the absence of a package.json in the project directory.

Options

| Option | Description | Default | | ------------- | ------------------------------------------------ | -------- | | host | The host of your Dokku server | None | | app | The name of your Dokku application | None | | localBranch | The local branch to deploy | main | | dokkuBranch | The deploy branch to push to on the Dokku server | master |

{
  "deploy": {
    "executor": "nx-dokku:deploy-src",
    "options": {
      "host": "server.example.com",
      "app": "my-dokku-app",
      "localBranch": "main"
    }
  }
}

Dokku Configuration

When opting for the deploy-src executor, the build directory of the Dokku app should align with the path to the project directory. Configure the build directory by running the following command on the Dokku server:

dokku builder:set my-dokku-app build-dir apps/my-app

🚀 Usage

To deploy your application, run:

nx deploy my-app

⭐ Tip: To unleash the true potential of Nx, use nx run affected -t deploy in your CI/CD pipeline.

🛠️ Troubleshooting

Host key verification failed

Ensure you've set up SSH key authentication with your Dokku host. Read more about it here.

🤝 Support

Encountered an issue or have suggestions for improvements? Feel free to raise an issue.

Contributions are welcome!