Dokploy Platform Setup

Overview

Dokploy is the self-hosted PaaS that runs our deployments. The CI/CD pipeline (see deploy-workflow) pushes images and then calls Dokploy deploy APIs (compose.deploy / application.deploy); Dokploy handles pulling images, running containers, and routing traffic.

Projects

VPS VPN

A standalone project with a WireGuard deployment that provides VPN access to the private network. All internal resources (databases, observability stack, etc.) are only reachable through this VPN — they are not exposed to the public internet.

Team members must connect to the WireGuard VPN before accessing any private resource.

DaraMex Dev

The development environment project. Contains all resources needed to run the full application stack.

Resources

Resource	Type	Source	Description
Infra	Docker Compose (custom)	GitHub repo (auto-synced)	API infrastructure (PostgreSQL, Redis, RabbitMQ)
Observability	Docker Compose (custom)	GitHub repo (auto-synced)	Observability stack (Grafana, Prometheus, Loki, Tempo, OTel Collector)
Api	Docker Compose (custom)	GitHub repo (auto-synced)	API application container
Docs	Application	Docker Hub image pull	VitePress docs site — pulls daramex25/daramex-docs
Panel	Application	Docker Hub image pull	React panel app — pulls daramex25/daramex-panel

Docker Compose resources read their docker-compose.yml directly from the GitHub repository, so any infra change merged to the deployment branch is automatically picked up on the next redeploy.

Application resources (Docs, Panel) are configured to pull a specific image from Docker Hub and run it. The CI/CD pipeline pushes the image and triggers a Dokploy API redeploy call.

Manual Configuration (one-time setup)

These steps were performed manually in the Dokploy UI and are not automated.

1. Docker Hub Registry

In Dokploy → Settings → Registry, a Docker Hub connection is registered with the daramex25 account credentials. This allows Dokploy to pull private images for the Application-type resources (Docs, Panel).

2. GitHub Source for Docker Compose

Each Docker Compose resource is configured to read its compose file directly from the GitHub repository instead of pasting the file content into Dokploy. This keeps the compose definitions version-controlled and in sync with the codebase.

3. DOCKER_CONFIG for private image pulls in Compose resources

By default, Dokploy Docker Compose resources do not use the registered Docker Hub credentials when pulling images referenced in docker-compose.yml. To fix this, add the following environment variable to any Compose resource that pulls from a private registry:

DOCKER_CONFIG=/root/.docker

This tells Docker (inside the Dokploy-managed compose) to use Dokploy's own Docker config directory, which contains the credentials registered in step 1. Without this, docker compose pull fails with authentication errors on private images.

4. Basic Auth for Docs (Traefik Middleware)

The docs site is protected with HTTP basic auth via a Traefik middleware to prevent public access.

Generate the password hash

On the server (or locally with apache2-utils installed):

apt-get install -y apache2-utils
htpasswd -nB your_username

This outputs a line like your_username:$2y$05$....

Configure the middleware in Dokploy

In the Dokploy UI, go to the Docs application → Advanced → Traefik and add a basicAuth middleware:

http:
  middlewares:
    docs-basic-auth:
      basicAuth:
        users:
          - 'your_username:$2y$05$hashed_password_here'

Attach the middleware to the routers

Add docs-basic-auth to both the HTTP and HTTPS routers for docs.daramex.org:

http:
  routers:
    # HTTP router — redirects to HTTPS + requires auth
    daramex-monorepo-dev-api-pclmca-router-5:
      rule: Host(`docs.daramex.org`)
      service: daramex-monorepo-dev-api-pclmca-service-5
      middlewares:
        - redirect-to-https
        - docs-basic-auth
      entryPoints:
        - web

    # HTTPS router — serves the docs + requires auth
    daramex-monorepo-dev-api-pclmca-router-websecure-5:
      rule: Host(`docs.daramex.org`)
      service: daramex-monorepo-dev-api-pclmca-service-5
      middlewares:
        - docs-basic-auth
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt

After saving, redeploy the Docs application so Traefik picks up the new middleware configuration.

Adding a New Environment

To replicate this setup for a new environment (e.g., Production):

1. Create a new Dokploy project (e.g., "DaraMex Prod").
2. Register Docker Hub credentials in Settings → Registry (if not already done globally).
3. Create the same resource types, pointing compose files to the appropriate branch.
4. Set DOCKER_CONFIG=/root/.docker on any Compose resource that pulls private images.
5. Add Dokploy API credentials and resource IDs as GitHub Environment secrets (DOKPLOY_API_KEY, DOKPLOY_API_COMPOSE_ID, DOKPLOY_PANEL_APP_ID, and if needed DOKPLOY_DOCS_APP_ID).
6. Configure the DOKPLOY_NOTIFY_MODE GitHub Actions variable (independent or all-or-nothing) to match your rollout policy.