Deployment Overview of Temporal on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Linux server running Debian-based distributions. The following prerequisites must be met before initiating the installation:

• Operating System: Debian or Ubuntu

• Privileges: Root access or sudo privileges

• Domain Configuration: A valid domain on the hostkey.in zone

• Ports: The server must allow traffic on the external port 443 for HTTPS access and specific internal ports for container communication.

FQDN of the Final Panel¶

The application is accessible via the following Fully Qualified Domain Name (FQDN) format:

temporal<Server ID>.hostkey.in:443

Replace <Server ID> with the specific identifier assigned to the server instance. The application is served over HTTPS on port 443.

File and Directory Structure¶

The deployment utilizes the following directory structure for configuration files, data storage, and certificates:

• /root/docker-compose: Contains the cloned GitHub repository and the main docker-compose-multirole_edited.yaml file.

• /root/nginx: Contains the Nginx and Certbot configuration files, including compose.yml.

• /data/nginx/user_conf.d/: Stores the specific Nginx server block configuration for the Temporal instance.

• /data/grafana/: Stores the Grafana configuration file (grafana.ini).

• /etc/letsencrypt/live/: Stores SSL certificates and keys for the domain.

• /var/lib/postgresql/data: Persistent storage volume for the PostgreSQL database.

Application Installation Process¶

The application is deployed using Docker and Docker Compose. The installation process involves the following steps:

1. System Updates: Update and upgrade all APT packages on the server.

2. Docker Installation: Install the Docker engine and the docker-compose utility.

3. Repository Cloning: Clone the official Temporal Docker Compose repository from https://github.com/temporalio/docker-compose.git to /root/docker-compose.

4. Loki Driver Installation: Install and enable the grafana/loki-docker-driver plugin for container logging.

5. Alias Configuration: Add an alias for tctl to the root user's .bashrc file to facilitate command-line interaction with the Temporal CLI.

6. Configuration Generation: Generate the docker-compose-multirole_edited.yaml file and Nginx configurations based on the deployment variables.

7. Service Startup: Start the multi-role Temporal server stack and the Nginx/Certbot stack using Docker Compose.

Access Rights and Security¶

Security is enforced through the following mechanisms:

• Firewall: The server must allow inbound traffic on port 443 (HTTPS). Internal container ports are exposed only within the Docker network or mapped to specific host ports for monitoring.

• SSL/TLS: All external traffic is encrypted using SSL certificates managed by Certbot.

• User Access: The deployment scripts run with root privileges. The tctl alias is configured for the root user.

• Network Isolation: All Temporal services communicate over a dedicated Docker bridge network named temporal-network.

Databases¶

The deployment utilizes two primary database systems:

• PostgreSQL:

  • Role: Stores Temporal history and visibility data.

  • Image: postgres:${POSTGRESQL_VERSION}

  • Storage: Data is persisted in the /var/lib/postgresql/data volume.

  • Connection: Internal services connect via the hostname postgresql on the default port.

• Elasticsearch:

  • Role: Used for visibility and archival data.

  • Image: elasticsearch:${ELASTICSEARCH_VERSION}

  • Configuration: Single-node discovery with security disabled (xpack.security.enabled=false).

  • Connection: Internal services connect via the hostname elasticsearch on port 9200.

Docker Containers and Their Deployment¶

The application consists of multiple Docker containers orchestrated via docker-compose-multirole_edited.yaml. The containers are deployed in the following order based on dependencies:

• loki: Log aggregation service.

• elasticsearch: Search and analytics engine.

• postgresql: Relational database.

• temporal-history: Handles history service logic.

• temporal-matching: Handles matching service logic.

• temporal-frontend: Handles frontend service logic (two instances: temporal-frontend and temporal-frontend2).

• temporal-worker: Handles worker service logic.

• temporal-admin-tools: Administrative CLI tools.

• temporal-ui: Web user interface.

• temporal-nginx: Internal Nginx proxy for Temporal services.

• prometheus: Metrics collection.

• grafana: Metrics visualization.

• jaeger-all-in-one: Distributed tracing.

• otel-collector: OpenTelemetry collector.

All containers utilize the grafana/loki-docker-driver for logging, pushing logs to the local Loki instance.

Proxy Servers¶

External access is managed through an Nginx reverse proxy configured with Certbot for SSL termination.

• Nginx Configuration:

  • Location: /root/nginx/compose.yml

  • Image: jonasal/nginx-certbot:latest

  • Function: Handles SSL certificate generation and renewal, and proxies traffic to the internal Temporal UI, Grafana, and Prometheus services.

• Routing:

  • The root path / proxies to the Temporal UI running on internal port 8080.

  • The /grafana/ path proxies to the Grafana service.

  • The /prometheus/ path proxies to the Prometheus service.

• SSL: Certificates are stored in /etc/letsencrypt/live/ and are automatically renewed by the Certbot container.

Permission Settings¶

File and directory permissions are set as follows during the deployment:

• /root/nginx: Mode 0644, owned by root:root.

• /root/docker-compose: Mode 0644, owned by root:root.

• /data/nginx/user_conf.d/: Mode 0644, owned by root:root.

• /data/grafana/: Mode 0644, owned by root:root.

• Configuration files generated by templates are set to 0644 with root ownership.

Location of Configuration Files and Data¶

The following table lists the critical configuration files and their locations:

Available Ports for Connection¶

The following ports are exposed on the host for external or internal access:

Starting, Stopping, and Updating¶

Service management is handled via Docker Compose commands executed from the specific project directories.

• Start Temporal Services:

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

• Stop Temporal Services:

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

• Start Nginx/Certbot Services:

  cd /root/nginx
  docker compose up -d
  

• Stop Nginx/Certbot Services:

  cd /root/nginx
  docker compose down
  

• Update 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
  

• Access Temporal CLI: The tctl alias is configured in /root/.bashrc. After sourcing the file, run:

  tctl