How to Self-Host Temporal on a VPS (Complete Guide)

Temporal is an open-source, distributed, and scalable workflow orchestration engine used by developers to build resilient, long-running applications. Hosting Temporal on a VPS can give you full control over your infrastructure, cost savings, and customization. This guide walks you through the process of installing Temporal in a Docker container on a VPS provider, ensuring a smooth setup suitable for dev, homelab, or production environments.

Why Self-Host Temporal?

Self-hosting Temporal allows you to:

• Gain full control over your workflow orchestration environment.
• Reduce costs compared to managed solutions.
• Customize configurations for your needs.
• Learn and experiment with distributed systems.

Popular VPS providers like Contabo (€5.99/month), Hetzner Cloud (€4.15/month), DigitalOcean ($6), and Vultr ($6) offer affordable, high-performance options perfect for hosting Temporal.

Prerequisites

• A VPS with a public IP, Linux OS (Ubuntu 22.04 preferred).
• Root or sudo privileges.
• Basic knowledge of Docker, Linux command line, and networking.
• A domain or static IP for SSL setup (optional but recommended).

Step 1: Prepare Your VPS

Update your server packages and install Docker:

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io
sudo systemctl enable --now docker

Verify Docker installation:

docker --version

For operational ease, add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Step 2: Set Up Docker Compose

Temporal recommends Docker Compose for managing multi-container setups. Install Docker Compose:

sudo apt install -y docker-compose

Check version:

docker-compose --version

Step 3: Download Temporal Docker Compose Files

Temporal provides example configurations. Clone the Temporal repository:

git clone https://github.com/temporalio/docker-compose.git
cd docker-compose

Alternatively, create your own docker-compose.yaml for customizing your setup.

Step 4: Configure your Docker Compose File

Create or modify the docker-compose.yaml file to suit your needs. Here’s a simplified example for a development setup:

version: '3.8'

services:
  temporal:
    image: temporalio/server:latest
    environment:
      - TEMPORAL_CLI_ADDRESS=temporal:7233
    ports:
      - "7233:7233"
    networks:
      - temporal-network
    restart: always

  frontend:
    image: temporalio/web:latest
    ports:
      - "8080:8080"
    environment:
      - TEMPORAL_HOST=https://localhost:7233
    depends_on:
      - temporal
    networks:
      - temporal-network

networks:
  temporal-network:
    driver: bridge

Adjust configurations based on your requirements. For production, consider deploying with SSL, persistent storage, and secure credentials.

Step 5: Launch Temporal

Deploy your stack:

docker-compose up -d

Check if services are running:

docker ps

You should see the Temporal server and web UI containers active.

Step 6: Access the Temporal Web UI

Open your browser to the server’s IP or domain at port 8080. You’ll find a functional interface to manage workflows.

Step 7: Set Up TLS (Optional but Recommended)

For production deployments, secure web traffic:

• Obtain SSL certificates via Let’s Encrypt (certbot).
• Configure reverse proxy (NGINX or Caddy) to terminate TLS.
• Update your Docker Compose with proxy settings.

Monitoring and Maintenance

Regularly update containers:

docker-compose pull
docker-compose down
docker-compose up -d

Ensure backups of your workflows and metadata, especially if deploying to production.

VPS Provider Comparison

For more options, see our full VPS comparison.

FAQs

How difficult is it to self-host Temporal on a VPS?

Self-hosting Temporal on a VPS involves configuring Docker, Docker Compose, and networking properly. For developers familiar with Linux and Docker, the process is straightforward, typically taking less than an hour. Additional setup like securing access with SSL or clustering can increase complexity but are manageable with step-by-step guides and community support on /r/selfhosted or awesome-selfhosted.

Can I run Temporal on a low-cost VPS?

Yes. Providers like Hetzner Cloud (€4.15/month) or Contabo (€5.99/month) offer sufficient resources for small to medium workloads. Temporal’s requirements vary based on usage, but a VPS with 2 CPU cores and 4GB RAM is generally adequate for development and testing environments. For production, monitor resource usage and scale accordingly.

How do I secure my self-hosted Temporal instance?

To ensure security, set up SSL/TLS for web access (using Let’s Encrypt or paid certs), restrict network access with firewalls, and configure authentication mechanisms. For production, use reverse proxies like NGINX or Caddy with TLS termination, and enable secure credentials management. Always keep your Docker containers updated to mitigate vulnerabilities.

Conclusion

Self-hosting Temporal on a VPS offers full control over your workflow orchestration environment at an affordable price. With Docker and Docker Compose, deployment is straightforward and reproducible. Whether for development, testing, or small-scale production, the steps above guide you from initial setup to a fully functional Temporal instance. Explore more open-source self-hosting projects and optimize your homelab with insights from /r/selfhosted and awesome-selfhosted communities.

Looking for more hosting ideas? Check out our full VPS comparison to find the best provider for your self-hosting needs.