Max Vojtkov usr_unknown

Joined on 2024-07-08

@maxvojtkov/pulumi-dokploy (0.1.0)

Published 2026-08-09 10:13:09 +00:00 by usr_unknown in usr_unknown/pulumi-dokploy

Set up this registry in your project .npmrc file:

@maxvojtkov:registry=

To install the package using npm, run the following command:

npm install @maxvojtkov/pulumi-dokploy@0.1.0

or add it to the package.json file:

"@maxvojtkov/pulumi-dokploy": "0.1.0"

For more information on the npm registry, see the documentation.

pulumi-dokploy

A Pulumi provider for Dokploy: projects, environments, applications, Compose stacks, managed databases, domains, mounts, ports, redirects, basic auth, registries, SSH keys, certificates and backup destinations.

This is a bridged provider. All of the behaviour lives in terraform-provider-dokploy; pulumi-terraform-bridge turns it into a Pulumi package with typed SDKs for TypeScript, Python, Go and .NET. The two providers stay in lockstep — a resource added upstream shows up here after a make tfgen.

import * as dokploy from "@maxvojtkov/pulumi-dokploy";

const shop = new dokploy.Project("shop", { name: "shop" });

const db = new dokploy.Postgres("db", {
    name: "shop-db",
    environmentId: shop.defaultEnvironmentId,
    dockerImage: "postgres:16-alpine",
    databaseName: "shop",
    databaseUser: "shop",
    databasePassword: dbPassword,
});

const api = new dokploy.Application("api", {
    name: "api",
    environmentId: shop.defaultEnvironmentId,
    sourceType: "docker",
    dockerImage: "ghcr.io/acme/api:1.4.0",
    env: pulumi.interpolate`DATABASE_URL=postgresql://shop:${dbPassword}@${db.appName}:5432/shop`,
});

new dokploy.Domain("api", {
    applicationId: api.id,
    domainType: "application",
    host: "api.example.com",
    port: 3000,
    https: true,
    certificateType: "letsencrypt",
});

Installing
Configuration
Resources and data sources
Deploying from CI
Differences from the Terraform provider
Examples
Development
Releasing

Installing

The SDKs live in this Gitea instance's package registries, and the plugin binary is resolved automatically from this repository's Gitea releases — the download URL is baked into the schema, so pulumi up fetches it without any configuration.

The SDKs do need one-time registry configuration, because none of these package managers know about a private host by default.

TypeScript / JavaScript

npm config set @maxvojtkov:registry \
  https://gitea.coolify.vojtkov.dev/api/packages/usr_unknown/npm/
npm install @maxvojtkov/pulumi-dokploy

Python

pip install pulumi_dokploy \
  --index-url https://gitea.coolify.vojtkov.dev/api/packages/usr_unknown/pypi/simple

.NET

dotnet nuget add source \
  https://gitea.coolify.vojtkov.dev/api/packages/usr_unknown/nuget/index.json \
  --name gitea-dokploy
dotnet add package Maxvojtkov.Dokploy

Go — the module path stays github.com/maxvojtkov/... even though nothing is hosted on GitHub, so point the proxy at Gitea and skip the public checksum database for that path:

export GOPROXY=https://gitea.coolify.vojtkov.dev/api/packages/usr_unknown/go,direct
export GONOSUMDB='github.com/maxvojtkov/*'
go get github.com/maxvojtkov/pulumi-dokploy/sdk/go/dokploy

If the registries are private, add credentials the usual way for each tool — an _authToken in .npmrc, --extra-index-url with basic auth for pip, and --username/--password on the dotnet nuget add source.

Before the first release, build and install it locally instead:

make install VERSION=0.1.0

That drops pulumi-resource-dokploy into the local plugin cache, so pulumi up finds it without a network fetch.

Do I need the static SDK?

Not necessarily. Pulumi can consume the Terraform provider directly, with no build step and no published SDK:

pulumi package add terraform-provider maxvojtkov/dokploy

That generates a local SDK on the spot and is the fastest way to try things. Use this repository when you want a versioned, published package — stable tokens across releases, real package-manager installs, and SDKs your teammates can depend on without a codegen step.

Configuration

Setting	Environment variable	Required	Description
`dokploy:host`	`DOKPLOY_HOST`	yes	Base URL of the instance, e.g. `https://dokploy.example.com`. Trailing `/api` optional.
`dokploy:apiKey`	`DOKPLOY_API_KEY`	yes	Token from Settings → Profile → API/CLI. Always treated as a secret.
`dokploy:timeoutSeconds`	`DOKPLOY_TIMEOUT_SECONDS`	no	Per-request timeout. Defaults to `60`.
`dokploy:insecureSkipVerify`	—	no	Skip TLS verification. Only for self-signed certificates.

pulumi config set dokploy:host https://dokploy.example.com
pulumi config set --secret dokploy:apiKey "$DOKPLOY_API_KEY"

Resources and data sources

Group	Resources
Structure	`Project`, `Environment`
Services	`Application`, `Compose`
Databases	`Postgres`, `MySql`, `MariaDb`, `Mongo`, `Redis`
Networking	`Domain`, `Mount`, `Port`, `Redirect`, `Security`
Account	`Registry`, `SshKey`, `Certificate`, `Destination`

Data sources: getProject, getProjects, getEnvironment, getApplication, getServers.

Deploying from CI

Like the Terraform provider, this one manages configuration, not rollouts. Creating an Application writes its definition; it does not build or start anything.

dokploy-deploy-action covers the other half on GitHub Actions and Gitea Actions: it triggers a deployment, waits for the build, and fails the job when the deployment fails. Export the application id from your stack and hand it over.

export const apiApplicationId = api.id;

- uses: https://gitea.coolify.vojtkov.dev/usr_unknown/dokploy-deploy-action@v1
  with:
    host: ${{ secrets.DOKPLOY_HOST }}
    api-key: ${{ secrets.DOKPLOY_API_KEY }}
    application-id: ${{ steps.stack.outputs.apiApplicationId }}
    docker-image: ghcr.io/acme/api:${{ github.sha }}

Differences from the Terraform provider

Everything is a mechanical translation of the Terraform provider, with three Pulumi conventions applied on top:

Attribute names are camelCase. environment_id → environmentId, default_environment_id → defaultEnvironmentId, and so on.
name is auto-generated when you omit it. Pulumi appends a random suffix to the logical resource name, the same way the AWS provider does. Pass name explicitly whenever the Dokploy-side name matters to you.
The web-service Terraform module has no direct equivalent. Write it as a ComponentResource instead — see examples/typescript/webService.ts, which is a port of that module.

The known API quirks documented upstream apply here unchanged, because it is the same code doing the work.

Examples

examples/typescript — a full environment: project, staging environment, Postgres, Redis, a GitHub-built web service behind a domain, a basic-auth-protected internal tool, and a Compose stack.
examples/python — a small project, database and app.

Development

Requirements: Go 1.25+, Node 20+, Python 3.9+, .NET 8+, and pulumi.

make tfgen        # regenerate schema.json and bridge-metadata.json
make provider     # build the plugin binary into bin/
make build_sdks   # regenerate all four SDKs
make install      # install the plugin into the local Pulumi plugin cache
make lint test

provider/resources.go is the whole mapping layer: Terraform type names to Pulumi tokens, and Terraform provider configuration to Pulumi configuration. Adding an upstream resource means adding one line there and re-running make tfgen build_sdks.

The upstream dependency

provider/go.mod currently carries:

replace github.com/maxvojtkov/terraform-provider-dokploy => ../../dokploy-teraform

so the two repositories can be developed side by side. CI reproduces that layout by checking the upstream provider out as a sibling directory.

The replace is load-bearing here, not just a convenience: the module path says github.com, but the code lives on Gitea, and Go has no way to discover that on its own. It can go away once the upstream provider is published to Gitea's Go registry, at which point the module resolves through GOPROXY:

export GOPROXY=https://gitea.coolify.vojtkov.dev/api/packages/usr_unknown/go,direct
export GONOSUMDB='github.com/maxvojtkov/*'
cd provider && go mod edit -dropreplace github.com/maxvojtkov/terraform-provider-dokploy \
  && go get github.com/maxvojtkov/terraform-provider-dokploy@v0.1.0

The upstream provider exposes itself through its shim package (shim.NewProvider(version)), because internal/provider is not importable from outside that module.

Releasing

Tag the repository and the release workflow does the rest:

git tag v0.1.0 && git push origin v0.1.0

GoReleaser publishes the plugin binaries to a Gitea release first — Pulumi resolves the plugin from there, so it has to exist before anyone installs an SDK — and then the four SDKs go to this instance's npm, PyPI, NuGet and Go registries.

No secrets to configure. Every step authenticates with secrets.GITEA_TOKEN, which Gitea injects into each run automatically.

Two things the workflow depends on:

A registered act_runner with an ubuntu-latest label, and enough of a toolchain for Go, Node, Python and .NET.
The upstream terraform-provider-dokploy repository being readable by that token, since the replace directive needs it checked out as a sibling.

License

MPL-2.0.

Dependencies

ID	Version
@pulumi/pulumi	^3.0.0

Development Dependencies

ID	Version
@types/node	^18
typescript	^4.6.0

pulumi dokploy paas docker deployment category/cloud category/infrastructure

Details

npm

usr_unknown/pulumi-dokploy

2026-08-09 10:13:09 +00:00

Project Site

MPL-2.0

latest

40 KiB

Assets (1)

pulumi-dokploy-0.1.0.tgz 40 KiB

Versions (1) View all

0.1.0

2026-08-09

Issues