apx-dokploy 0.1.0__py3-none-any.whl

apx_dokploy/__init__.py

@@ -0,0 +1,5 @@
+"""Dokploy for Action Platform: the `dokploy` deploy target, its overlay, and tools to read what runs there."""
+
+from apx_dokploy.plugin import DokployPlugin
+
+__all__ = ["DokployPlugin"]

apx_dokploy/cli.py

@@ -0,0 +1,38 @@
+"""`action-platform dokploy …` — the same reads as the tools, from a terminal."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from apx_dokploy.settings import connect
+from apx_dokploy.tools import applications_of, deployments_of, projects_of
+
+app = typer.Typer(
+    help="Dokploy: projects, applications, deployments.", no_args_is_help=True
+)
+options: Any | None = None
+
+
+@app.command("projects")
+def projects() -> None:
+    """List the projects and their environments."""
+    for p in projects_of(connect(options)):
+        typer.echo(f"{p.name}\t{', '.join(p.environments)}\t{p.id}")
+
+
+@app.command("applications")
+def applications(project: str = typer.Option("", help="Only this project")) -> None:
+    """List the applications, their status and image."""
+    for a in applications_of(connect(options), project):
+        typer.echo(
+            f"{a.project}/{a.environment}/{a.app_name}\t{a.status}\t{a.image or '-'}\t{a.id}"
+        )
+
+
+@app.command("deployments")
+def deployments(application_id: str, limit: int = typer.Option(10)) -> None:
+    """Deployment history of one application."""
+    for d in deployments_of(connect(options), application_id, limit):
+        typer.echo(f"{d.created_at}\t{d.status}\t{d.title or '-'}\t{d.id}")

apx_dokploy/client.py

@@ -0,0 +1,144 @@
+"""The Dokploy REST API (`/api/<router>.<procedure>`, `x-api-key`) and the OCI registry the image lives in — plain urllib, no client library."""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from typing import Any
+from urllib import error, parse, request
+
+from action_platform.core.exception import DeployError
+
+TIMEOUT = 30
+MANIFEST_TYPES = ", ".join(
+    [
+        "application/vnd.oci.image.index.v1+json",
+        "application/vnd.oci.image.manifest.v1+json",
+        "application/vnd.docker.distribution.manifest.list.v2+json",
+        "application/vnd.docker.distribution.manifest.v2+json",
+    ]
+)
+
+
+class ApiError(DeployError):
+    def __init__(self, status: int, detail: str) -> None:
+        super().__init__(f"dokploy answered {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+class Dokploy:
+    """One Dokploy instance: `get` and `post` against its API with the key."""
+
+    def __init__(self, url: str, api_key: str) -> None:
+        self.url = url.rstrip("/")
+        self.api_key = api_key
+
+    def get(self, procedure: str, **query: Any) -> Any:
+        target = f"{self.url}/api/{procedure}"
+
+        if query:
+            target += "?" + parse.urlencode(query)
+
+        return self._send("GET", target, None)
+
+    def post(self, procedure: str, body: dict[str, Any] | None = None) -> Any:
+        return self._send("POST", f"{self.url}/api/{procedure}", body or {})
+
+    def _send(self, method: str, target: str, body: dict[str, Any] | None) -> Any:
+        data = json.dumps(body).encode() if body is not None else None
+        req = request.Request(target, data=data, method=method)
+        req.add_header("x-api-key", self.api_key)
+        req.add_header("accept", "application/json")
+
+        if data is not None:
+            req.add_header("content-type", "application/json")
+
+        try:
+            with request.urlopen(req, timeout=TIMEOUT) as response:
+                text = response.read().decode(errors="replace")
+        except error.HTTPError as e:
+            raise ApiError(e.code, e.read().decode(errors="replace")[:500]) from e
+        except (error.URLError, TimeoutError) as e:
+            raise DeployError(f"dokploy unreachable at {self.url}: {e}") from e
+
+        return json.loads(text) if text.strip() else None
+
+
+def image_exists(
+    image: str,
+    tag: str,
+    username: str | None = None,
+    password: str | None = None,
+) -> bool:
+    """Whether `image:tag` is in its registry — a manifest HEAD, with the bearer token the registry asks for when it asks for one."""
+    registry, name = _split(image)
+    target = f"https://{registry}/v2/{name}/manifests/{tag}"
+    basic = (
+        base64.b64encode(f"{username}:{password}".encode()).decode()
+        if username and password
+        else None
+    )
+    status, challenge = _head(target, "Basic " + basic if basic else None)
+
+    if status == 401 and challenge:
+        token = _token(challenge, basic)
+        status, _ = _head(target, f"Bearer {token}")
+
+    if status == 200:
+        return True
+
+    if status == 404:
+        return False
+
+    raise DeployError(f"registry {registry} answered {status} for {name}:{tag}")
+
+
+def _split(image: str) -> tuple[str, str]:
+    head, _, rest = image.partition("/")
+
+    if rest and ("." in head or ":" in head or head == "localhost"):
+        return head, rest
+
+    name = image if "/" in image else f"library/{image}"
+
+    return "registry-1.docker.io", name
+
+
+def _head(target: str, authorization: str | None) -> tuple[int, str]:
+    req = request.Request(target, method="HEAD")
+    req.add_header("accept", MANIFEST_TYPES)
+
+    if authorization:
+        req.add_header("authorization", authorization)
+
+    try:
+        with request.urlopen(req, timeout=TIMEOUT) as response:
+            return response.status, ""
+    except error.HTTPError as e:
+        return e.code, e.headers.get("www-authenticate", "")
+    except (error.URLError, TimeoutError) as e:
+        raise DeployError(f"registry unreachable: {e}") from e
+
+
+def _token(challenge: str, basic: str | None) -> str:
+    fields = dict(re.findall(r'(\w+)="([^"]*)"', challenge))
+    realm = fields.get("realm")
+
+    if not realm:
+        raise DeployError(f"registry challenge not understood: {challenge}")
+
+    query = {k: v for k, v in fields.items() if k in ("service", "scope")}
+    req = request.Request(f"{realm}?{parse.urlencode(query)}")
+
+    if basic:
+        req.add_header("authorization", f"Basic {basic}")
+
+    try:
+        with request.urlopen(req, timeout=TIMEOUT) as response:
+            data = json.loads(response.read().decode())
+    except error.HTTPError as e:
+        raise DeployError(f"registry token refused ({e.code}): check the credentials")
+
+    return data.get("token") or data.get("access_token") or ""

apx_dokploy/overlays/cloud/dokploy/cookiecutter.json

@@ -0,0 +1,14 @@
+{
+  "project_name": "My Project",
+  "project_slug": "{{ cookiecutter.project_name|lower|replace(' ', '-') }}",
+  "github_owner": "actionplatform",
+  "package_name": "{{ cookiecutter.project_slug|replace('-', '_') }}",
+  "language": ["python", "node", "go", "java", "kotlin", "ruby"],
+  "type": ["web"],
+  "ci": ["github", "gitlab", "jenkins"],
+  "_kind": "cloud",
+  "_cloud": "dokploy",
+  "_description": "Docker image published by the CI on every release, run by Dokploy",
+  "_types": ["web"],
+  "_copy_without_render": [".github/workflows/docker-publish.yml"]
+}

apx_dokploy/overlays/cloud/dokploy/hooks/post_gen_project.py

@@ -0,0 +1,9 @@
+"""Cloud overlay post-gen: keep the image workflow only for the CI it belongs to."""
+
+import shutil
+from pathlib import Path
+
+CI = "{{ cookiecutter.ci }}"
+
+if CI != "github" and Path(".github").exists():
+    shutil.rmtree(".github")

apx_dokploy/overlays/cloud/dokploy/{{cookiecutter.project_slug}}/.dockerignore

@@ -0,0 +1,11 @@
+.git/
+.github/
+.venv/
+node_modules/
+__pycache__/
+*.pyc
+.env
+tests/
+docs/
+build/
+dist/

apx_dokploy/overlays/cloud/dokploy/{{cookiecutter.project_slug}}/.github/workflows/docker-publish.yml

@@ -0,0 +1,52 @@
+name: Package Docker
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+concurrency:
+  group: image-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build and push ${{ github.ref_name }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Read the version from the tag
+        id: version
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          version="${tag#v}"
+          [ "$version" = "$tag" ] && version="$(cat LAST_VERSION)"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "image=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
+
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ${{ steps.version.outputs.image }}:${{ steps.version.outputs.version }}
+            ${{ steps.version.outputs.image }}:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - run: echo "${{ steps.version.outputs.image }}:${{ steps.version.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"

apx_dokploy/overlays/cloud/dokploy/{{cookiecutter.project_slug}}/DEPLOY.md

@@ -0,0 +1,42 @@
+# Deploy — Dokploy
+
+Overlay `cloud/dokploy`. The CI builds the image on every release and Dokploy pulls it; the platform tells Dokploy which tag to run.
+
+| | |
+|---|---|
+| Image | `ghcr.io/{{ cookiecutter.github_owner }}/{{ cookiecutter.project_slug }}:<version>` — `.github/workflows/docker-publish.yml`, on every published release |
+| Dokploy project | `{{ cookiecutter.project_slug }}` |
+| Dokploy environment | one per scope: `dev`, `prod` |
+| Application | `{{ cookiecutter.project_slug }}-<scope>`, listens on port 8000 |
+
+## Set up once
+
+1. In Dokploy, Settings → API Keys: create a key. Put it and the instance url in the plugin's options (Plugins → Dokploy → Configure on the platform; `DOKPLOY_URL` and `DOKPLOY_API_KEY` on a machine).
+2. Is the GitHub package private? Give the plugin a registry username and a token with `read:packages`, or make the package public under the repository's Packages settings.
+3. `platform.toml`:
+
+```toml
+[deploy]
+target = "dokploy"
+
+[deploy.domains]
+prod = "{{ cookiecutter.project_slug }}.example.com"
+```
+
+The first deploy creates the project, the environment, the application and the domain (Let's Encrypt). Point the DNS record at the Dokploy server before that.
+
+## Every release
+
+```bash
+action-platform release minor        # tags vX.Y.Z; the workflow publishes the image
+action-platform deploy --dry-run     # readiness: settings, image published, key accepted, application state
+action-platform deploy               # saveDockerProvider(<image>:<version>) + deploy, followed to done
+```
+
+`rollback` redeploys the previous version from the application's deployment history; `diagnose` reports the status, the image and the url.
+
+## Locally
+
+```bash
+docker compose up --build            # http://localhost:8000
+```

apx_dokploy/overlays/cloud/dokploy/{{cookiecutter.project_slug}}/Dockerfile

@@ -0,0 +1,26 @@
+# Two stages, the same shape for every language: the build image assembles the app with ap-build,
+# the runtime image runs it. The app serves HTTP on $PORT.
+{%- set lang = "java" if cookiecutter.language in ["java", "kotlin"] else cookiecutter.language %}
+FROM ghcr.io/actionplatform/build-{{ lang }}:0 AS build
+ARG TARGETARCH
+WORKDIR /w
+COPY . .
+RUN AP_ARCH=$([ "$TARGETARCH" = "amd64" ] && echo x86_64 || echo arm64) AP_ARTIFACTS=/out ap-build package
+
+FROM ghcr.io/actionplatform/runtime-{{ lang }}:0
+WORKDIR /app
+COPY --from=build /out /app
+ENV PORT=8000
+EXPOSE 8000
+{%- if cookiecutter.language == "python" %}
+ENV PYTHONPATH=/app
+CMD ["-m", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
+{%- elif cookiecutter.language == "node" %}
+CMD ["dist/server.js"]
+{%- elif cookiecutter.language == "go" %}
+ENTRYPOINT ["/app/bootstrap"]
+{%- elif cookiecutter.language == "ruby" %}
+CMD ["bundle", "exec", "rackup", "-s", "webrick", "-o", "0.0.0.0", "-p", "8000"]
+{%- else %}
+CMD ["-jar", "/app/app.jar", "--server.port=8000"]
+{%- endif %}

apx_dokploy/overlays/cloud/dokploy/{{cookiecutter.project_slug}}/docker-compose.yml

@@ -0,0 +1,9 @@
+services:
+  app:
+    build: .
+    image: {{ cookiecutter.project_slug }}:local
+    ports:
+      - "8000:8000"
+    environment:
+      SCOPE: development
+    restart: unless-stopped

apx_dokploy/overlays/index.json

@@ -0,0 +1,10 @@
+{
+  "clouds": [
+    {
+      "id": "dokploy",
+      "description": "Docker image published by the CI on every release, run by Dokploy",
+      "types": ["web"],
+      "languages": ["python", "node", "go", "java", "kotlin", "ruby"]
+    }
+  ]
+}

apx_dokploy/plugin.py

@@ -0,0 +1,64 @@
+"""The plugin: the dokploy overlay, `action-platform dokploy` commands, `dokploy_*` tools, and the options an organization fills in."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from action_platform.abc import Option, Plugin, Surface
+
+from apx_dokploy import cli
+from apx_dokploy.tools import register_tools
+
+
+class DokployPlugin(Plugin):
+    slug = "dokploy"
+    name = "Dokploy"
+    description = (
+        "Deploy a Docker image the CI publishes to a Dokploy instance; "
+        "read its projects, applications and deployments"
+    )
+    min_core = "0.28.1"
+    needs = [
+        "env: DOKPLOY_URL, DOKPLOY_API_KEY on a machine (the plugin's options on the platform)",
+        "net: the Dokploy instance's url; the image registry (ghcr.io by default)",
+    ]
+    options = [
+        Option(
+            "url",
+            "Dokploy URL",
+            "url",
+            help="Where the Dokploy dashboard answers, https://dokploy.example.com. A project may override it with [deploy] url.",
+            required=True,
+        ),
+        Option(
+            "api_key",
+            "API key",
+            "secret",
+            help="Generated under Settings > API Keys in Dokploy. Deploys, creates and deletes applications on your behalf; never written to a repository.",
+            required=True,
+        ),
+        Option(
+            "registry_username",
+            "Registry username",
+            "text",
+            help="Only for a private image registry: the user Dokploy pulls with. Empty for a public image.",
+        ),
+        Option(
+            "registry_password",
+            "Registry password",
+            "secret",
+            help="The token that goes with the registry username (a GitHub token with read:packages for ghcr.io).",
+        ),
+    ]
+
+    @property
+    def overlays(self) -> Path:
+        return Path(__file__).parent / "overlays"
+
+    def register(self, surface: Surface) -> None:
+        if surface.mcp is not None:
+            register_tools(surface.mcp, surface.options)
+
+        if surface.cli is not None:
+            cli.options = surface.options
+            surface.cli.add_typer(cli.app, name="dokploy")

apx_dokploy/settings.py

@@ -0,0 +1,46 @@
+"""Where a value comes from, in order: the target's own argument, what the deploy job carries (`AP_DOKPLOY_<KEY>` in `ctx.env`), the process environment (`AP_DOKPLOY_<KEY>`, then the plain name such as `DOKPLOY_URL`), the plugin's options file on this machine."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from action_platform.core.exception import ActionPlatformError
+from action_platform.plugins.options import FileOptions
+
+from apx_dokploy.client import Dokploy
+
+SLUG = "dokploy"
+PLAIN = {"url": "DOKPLOY_URL", "api_key": "DOKPLOY_API_KEY"}
+
+
+def setting(
+    key: str,
+    explicit: str | None = None,
+    env: dict[str, str] | None = None,
+    options: Any | None = None,
+) -> str | None:
+    name = f"AP_{SLUG}_{key}".upper()
+    stored = (options or FileOptions(SLUG)).get(key)
+    found = (
+        explicit
+        or (env or {}).get(name)
+        or os.environ.get(name)
+        or os.environ.get(PLAIN.get(key, ""))
+        or stored
+    )
+
+    return str(found) if found else None
+
+
+def connect(options: Any | None = None) -> Dokploy:
+    url = setting("url", options=options)
+    key = setting("api_key", options=options)
+
+    if not url or not key:
+        raise ActionPlatformError(
+            "dokploy: set the plugin's url and api_key options on the platform, "
+            "or DOKPLOY_URL and DOKPLOY_API_KEY on a machine"
+        )
+
+    return Dokploy(url, key)