dokku-temporal

A Dokku plugin for managing Temporal workflow platform services. Automatically handles database connectivity, schema setup, and provides both Temporal server and Web UI.

Prerequisites

# Install database plugin (choose one)
dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres
dokku plugin:install https://github.com/dokku/dokku-mysql.git mysql

Installation

dokku plugin:install https://github.com/dkgv/dokku-temporal.git temporal

Uninstallation

Before uninstalling the plugin, destroy all Temporal services:

# List all services
dokku temporal:list

# Destroy each service
dokku temporal:destroy <service> --force

# Then uninstall the plugin
dokku plugin:uninstall temporal

Quick Start

# Create and start service
dokku temporal:create my-temporal
dokku temporal:start my-temporal

# Create namespaces (optional)
dokku temporal:namespace:create my-temporal production --retention=90d

# Link to app
dokku temporal:link my-temporal my-app --namespace=production

# Access points:
# - Server (gRPC): localhost:7233
# - Web UI: http://localhost:8080 (local) or SSH tunnel (remote)

Commands

create <service> [db-type] [--db-service=existing_service]       Create Temporal service (postgres/mysql) or use existing database
start <service>                 Start service (server + Web UI)
stop <service>                  Stop service
restart <service>               Restart service
upgrade <service> [--version=<version>]                        Upgrade Temporal to latest or specific version
info <service>                  Show service information
list                            List all services
link <service> <app> [--namespace=<name>]                      Link service to app (sets TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE)
unlink <service> <app>          Unlink service from app
namespace:create <service> <name> [--retention=60d]            Create namespace (default: 60d retention)
namespace:list <service>        List all namespaces
namespace:delete <service> <name> [--force]                    Delete namespace
logs <service> [--db]           Show logs (add --db for database logs)
destroy <service> [--force]     Destroy service

Security

The Web UI is localhost-only for security.

Local development: Direct access at http://localhost:8080

Remote server (VPS): Use SSH tunnel:

ssh -L 8080:localhost:8080 user@your-server.com
# Then browse to http://localhost:8080

Why this approach:

• Zero configuration (no passwords/certificates)
• Maximum security (not accessible from internet)
• Works with any Dokku deployment
• Industry standard for admin interfaces

External Access

Temporal Server (for apps): Can be accessed externally on port 7233

# Set up DNS: my-temporal.example.com → your-server-ip
# Apps connect to: my-temporal.example.com:7233

Web UI: Localhost-only (use SSH tunnel)

Troubleshooting

Service won't start:

dokku postgres:info my-temporal  # Check database
dokku temporal:logs my-temporal  # Check Temporal logs

UI shows "Internal Error":

# For remote access, ensure SSH tunnel is active
ssh -L 8080:localhost:8080 user@your-server.com

# Then restart if needed
dokku temporal:restart my-temporal

Enable debug output:

# Get detailed debugging information for troubleshooting
DOKKU_TRACE=1 dokku temporal:start my-temporal
DOKKU_TRACE=1 dokku temporal:create my-temporal

Database issues: Plugin auto-handles connectivity, IP resolution, and container startup.

Examples

# Using existing database
dokku postgres:create my-existing-db
dokku temporal:create my-temporal postgres --db-service=my-existing-db

# Upgrade to specific version
dokku temporal:upgrade prod-temporal --version=1.22.0

Architecture

• Database: PostgreSQL/MySQL container (via Dokku plugins) - can use existing database services
• Server: Temporal server with auto-setup (temporalio/auto-setup)
• UI: Web interface (temporalio/ui)
• Networking: Automatic IP-based connectivity (works on bridge network)

Environment variables set on linked apps:

TEMPORAL_ADDRESS=<server-ip>:7233
TEMPORAL_NAMESPACE=default  # or custom namespace via --namespace flag