Skip to content

Deployment Overview of Temporal on Server

Prerequisites and Basic Requirements

The deployment requires a Debian-based operating system with root privileges. The following components must be present on the server:

  • Docker Engine installed and running.
  • Docker Compose installed via the APT package manager.
  • The grafana/loki-docker-driver plugin installed and enabled for container logging.
  • Network access to GitHub for cloning the repository.
  • A valid domain name configured for SSL certificate generation via Certbot.
  • Ports 80 and 443 must be open for the Nginx reverse proxy and SSL termination.

File and Directory Structure

The application utilizes specific directories for configuration, data persistence, and logs. The following paths are created and managed during the deployment:

  • /root/docker-compose: Contains the cloned repository and the main docker-compose-multirole_edited.yaml configuration file.
  • /root/nginx: Stores the Nginx and Certbot Docker Compose configuration (compose.yml) and environment files.
  • /data/nginx/user_conf.d: Holds the Nginx server block configuration files for the specific domain.
  • /data/nginx/nginx-certbot.env: Contains environment variables for the Certbot service.
  • /data/grafana: Stores the Grafana configuration file (grafana.ini).
  • /var/lib/postgresql/data: Persistent volume for the PostgreSQL database.
  • ./deployment/loki/local-config.yaml: Configuration for the Loki logging service.
  • ./deployment/prometheus/config.yml: Configuration for the Prometheus monitoring service.
  • ./deployment/grafana/provisioning/datasources: Datasource provisioning for Grafana.
  • ./deployment/otel/otel-config.yaml: Configuration for the OpenTelemetry Collector.
  • ./deployment/nginx/nginx.conf: Nginx configuration for the internal Temporal load balancer.

Application Installation Process

The installation involves cloning the official Temporal Docker Compose repository and configuring the environment for a multi-role deployment.

  1. Update and upgrade all APT packages on the system.
  2. Install Docker Engine and Docker Compose.
  3. Clone the Temporal Docker Compose repository to /root/docker-compose: 
    git clone https://github.com/temporalio/docker-compose.git /root/docker-compose
  4. Install and enable the Loki Docker driver plugin: 
    docker plugin install grafana/loki-docker-driver:latest --alias loki
  5. Configure the tctl alias in the root user's shell profile to interact with the Temporal CLI: 
    alias tctl="docker exec temporal-admin-tools tctl"
    This alias is appended to /root/.bashrc.

Docker Containers and Their Deployment

The application is deployed using Docker Compose with a multi-role configuration. The deployment consists of the following containers:

  • Loki: Container for log aggregation (grafana/loki:latest).
  • Elasticsearch: Search engine for visibility data (elasticsearch:${ELASTICSEARCH_VERSION}).
  • PostgreSQL: Relational database for Temporal state (postgres:${POSTGRESQL_VERSION}).
  • Temporal Services:
    • temporal-history: Manages workflow history.
    • temporal-matching: Handles task queue matching.
    • temporal-frontend and temporal-frontend2: Expose the Temporal API.
    • temporal-worker: Executes background tasks.
    • temporal-admin-tools: Provides administrative CLI tools.
    • temporal-ui: Web interface for workflow management.
  • Monitoring and Observability:
    • prometheus: Metrics collection (prom/prometheus:v2.37.0).
    • grafana: Visualization dashboard (grafana/grafana:7.5.16).
    • jaeger-all-in-one: Distributed tracing (jaegertracing/all-in-one:1.37).
    • otel-collector: OpenTelemetry collector (otel/opentelemetry-collector:0.47.0).
  • Networking:
    • temporal-nginx: Internal Nginx instance (nginx:1.22.1) acting as a load balancer for frontend services.

The main Temporal stack is started using the docker-compose-multirole_edited.yaml file located in /root/docker-compose. The Nginx and Certbot stack is started using compose.yml located in /root/nginx.

Proxy Servers

The deployment utilizes two Nginx instances:

  1. Internal Load Balancer (temporal-nginx):

    • Runs inside the temporal-network Docker network.
    • Listens on port 7233.
    • Distributes traffic between temporal-frontend (port 7237) and temporal-frontend2 (port 7236).
    • Configuration is mounted from ./deployment/nginx/nginx.conf.

  2. External Reverse Proxy and SSL Termination:

    • Managed by the nginx-certbot service using the image jonasal/nginx-certbot:latest.
    • Runs in host network mode.
    • Handles SSL certificates via Let's Encrypt for the domain {{ prefix }}{{ server_id }}.{{ zone }}.
    • Routes traffic to internal services based on the configuration in /data/nginx/user_conf.d.
    • Exposes the following paths:
      • Main Temporal API path.
      • Grafana at /grafana/.
      • Prometheus at the configured Prometheus location.

SSL certificates are stored in the nginx_secrets volume, mapped to /etc/letsencrypt within the container.

Databases

The deployment uses two primary database systems:

  • PostgreSQL:

    • Image: postgres:${POSTGRESQL_VERSION}.
    • Container Name: temporal-postgresql.
    • Data Persistence: Mounted to /var/lib/postgresql/data.
    • Credentials: Defined by environment variables POSTGRES_USER and POSTGRES_PASSWORD.
    • Port: Exposed internally on ${POSTGRES_DEFAULT_PORT}.

  • Elasticsearch:

    • Image: elasticsearch:${ELASTICSEARCH_VERSION}.
    • Container Name: temporal-elasticsearch.
    • Configuration: Single-node discovery (discovery.type=single-node).
    • Security: Disabled (xpack.security.enabled=false).
    • Memory: Limited to 512MB (ES_JAVA_OPTS=-Xms512m -Xmx512m).
    • Port: Exposed on 9200.

Permission Settings

File and directory permissions are set as follows during the configuration phase:

  • /root/nginx: Created with 0644 permissions, owned by root:root.
  • /root/nginx/compose.yml: Created with 0644 permissions, owned by root:root.
  • /root/docker-compose/docker-compose-multirole_edited.yaml: Created with 0644 permissions, owned by root:root.
  • /data/nginx/user_conf.d/{{ prefix }}{{ server_id }}.{{ zone }}.conf: Created with 0644 permissions, owned by root:root.
  • /data/grafana: Created with 0644 permissions, owned by root:root.
  • /data/grafana/grafana.ini: Created with 0644 permissions, owned by root:root.

Starting, Stopping, and Updating

The services are managed via Docker Compose commands executed in their respective directories.

Starting the Temporal Stack: 

cd /root/docker-compose
docker compose -f docker-compose-multirole_edited.yaml up -d

Starting the Nginx and Certbot Stack: 

cd /root/nginx
docker compose up -d

Stopping the Services: To stop the Temporal stack: 

cd /root/docker-compose
docker compose -f docker-compose-multirole_edited.yaml down

To stop the Nginx and Certbot stack: 

cd /root/nginx
docker compose down

Updating the Services: To update the application, pull the latest images and restart the containers: 

cd /root/docker-compose
docker compose -f docker-compose-multirole_edited.yaml pull
docker compose -f docker-compose-multirole_edited.yaml up -d

Accessing the Temporal CLI: The tctl alias is configured in /root/.bashrc to execute commands inside the temporal-admin-tools container: 

tctl --help

question_mark
Is there anything I can help you with?
question_mark
AI Assistant ×