What a Temporal deployment is made of
A working Temporal Service is the server, a persistence database, a Visibility store and, usually, the Web UI. The server itself splits into four roles. You can run them together in one process on one machine, or as separate processes that scale on their own once load grows.
| Piece | What it does | Default ports |
|---|---|---|
| Frontend | Stateless gateway: rate limits, authorizes, validates and routes every API call | gRPC 7233, membership 6933 |
| History | Writes each workflow's event history and queues tasks when a workflow can move on | gRPC 7234, membership 6934 |
| Matching | Hosts task queues and hands tasks to your workers | gRPC 7235, membership 6935 |
| Worker (internal) | Runs Temporal's own system workflows and replication | membership 6939 |
| Web UI | Browse namespaces, workflows and their histories | 8080 in the Compose sample |
Your own workers are separate programs written with a Temporal SDK. They only ever talk to the Frontend, which is why 7233 is the one port clients need. Every port above can be changed in the server configuration.
Which database should hold it?
PostgreSQL is the easiest production choice for one server, because it is a single process you already know how to back up; Cassandra suits teams that already run a Cassandra ring. The documentation lists these supported versions:
- PostgreSQL 13.18, 14.15, 15.10 and 16.6
- MySQL 5.7 and 8.0 (8.0.19 or later, because of a known bug)
- Cassandra 3.11, 4.0, and 5.0.4 or later (earlier 5.0 releases are not supported)
- SQLite 3.x for development and testing only, never production
The Visibility store is what lets you list and filter workflows in the UI and CLI. Elasticsearch is the store Temporal recommends for production (v7, or v8 from server 1.18); OpenSearch 2 and later works from server 1.30.1. Since server 1.20 you can also keep Visibility in MySQL 8.0.17+, PostgreSQL 12+ or SQLite, which saves running a search cluster on a small install.
The setting you only get to choose once
numHistoryShards is fixed on the first start: change it later and the server ignores the new value. Shards decide how many database operations the service can run at once, so they cap throughput for the life of the cluster. Raising the count means building a new Temporal Service and migrating to it.
Temporal publishes no single right number. Its configuration example uses 512, and it suggests starting with one History process for every 500 shards. Pick a value sized for your expected peak, not today's traffic, then load-test before real workflows depend on it.
Why a whole server suits it
The History service records each workflow's progress in the database as it happens, so Temporal is only as steady as the disk underneath it. On a dedicated server all of the cores, memory and disks are yours, with no other customer on the hardware, so a noisy neighbour cannot stall your history writes in the middle of a batch run.
- Root access, so you install Docker, PostgreSQL and the Temporal binaries exactly as the docs describe.
- An unmetered port: workers polling, payloads and replication never turn into a traffic bill.
- A console of your own on rack servers, blades and the m510 and m710x cartridges, so a firewall rule that locks out SSH is a fix, not a ticket.
- Reinstalls from the control panel, any number of times, while you try layouts.
- Month to month, with no contract, which suits a project still deciding how big it will get.
For the database, disks matter more than cores: an NVMe server puts PostgreSQL on flash storage. A small cartridge suits a staging copy that does one job, a one-processor everyday server is the class most apps and databases start on, and the two-processor machines are built for a busy database, which is what a loaded Temporal install becomes. We keep the hardware and network running; Temporal itself is yours to manage.
A first install with Docker Compose
The project's Compose files are meant for development and testing. They are the quickest way to see Temporal working on your server, provided you keep them private. The default file starts PostgreSQL, Elasticsearch, the server and the UI, and it publishes 5432, 9200, 7233 and 8080 on every address with the database password set to temporal. Docker publishes ports to all host addresses unless told otherwise, and its rules are applied before ufw sees the traffic, so a host firewall will not save you here.
- Install Docker Engine and the Compose plugin following Docker's own guide for your distribution.
- Fetch the samples:
git clone https://github.com/temporalio/samples-server.git && cd samples-server/compose - Open
docker-compose.yml. Delete theportsentries of thepostgresqlandelasticsearchservices (the containers reach each other on the Compose network), and change the other two to127.0.0.1:7233:7233and127.0.0.1:8080:8080so only the server itself can reach them. - Replace the password
temporalin every variable that carries it (POSTGRES_PASSWORD,POSTGRES_PWD,SQL_PASSWORD) with one new value. PostgreSQL sets it only when its data directory is first created, so do this before the first start. - Start it with
docker compose up, as the project's README does; add-dto keep it running after you log out. - From your own computer, open a tunnel with
ssh -L 8080:127.0.0.1:8080 you@your-serverand browse tohttp://localhost:8080for the UI. - Point workers running on the same machine at
127.0.0.1:7233.
docker compose down -v removes the containers and their volumes, which deletes every workflow history in the database. To pause the stack and keep the data, use docker compose stop; the sample's database volume has no name, so after any docker compose down the next up starts empty.
If you only need something on your laptop, the CLI's temporal server start-dev is lighter still, but its own help warns it is not for production, and without --db-filename every workflow is lost when the process stops.
What production adds
For production, Temporal points to its Helm charts on Kubernetes, or to the server and UI as separate binaries managed by systemd behind a reverse proxy such as Nginx or Envoy. Either way you bring your own database and Visibility store and look after them.
- Lock the API. Without an
Authorizerthe server uses a no-op one that allows every request; anyone who can reach port 7233 can call any API. Configure an Authorizer with a ClaimMapper, and keep Temporal hosts off the open internet, guarded like a database. - Encrypt with mTLS. The
frontendandinternodeTLS sections take separate certificates; setrequireClientAuthand a client CA so only your workers connect. - Sign in to the UI. Set
TEMPORAL_AUTH_ENABLED=truewith your identity provider's client ID, secret, provider URL and callback, and the UI sends users through SSO. - Upgrade one minor version at a time, moving to the latest patch of your current minor first. Database schema updates are a separate step with the
temporalio/admin-toolsimage. - Watch three kinds of metrics: service requests, errors and latency; persistence latency and errors; and workflow completions by outcome.
- Back up the database with its own tools (
pg_dumpfor PostgreSQL) and test a restore on a spare machine before you need it.
If you would rather not run the control plane of a cluster yourself, managed Kubernetes keeps it running while the nodes stay your own servers; to install everything yourself, see Kubernetes on bare metal.
When one server is the wrong answer
A single machine is a single point of failure: if the box or its disk goes, workflows pause until it is back. That is acceptable for internal jobs and staging, less so for payments that must never stall. Self-hosted Temporal also ships without role-based access control or audit logging, so if your organisation needs those you build them around it.
Spreading the services across several servers works, but membership and gRPC traffic then crosses the network between machines, so internode mTLS stops being optional. And Temporal releases can arrive as often as every two weeks; somebody has to own the upgrades.
Questions people ask
- Is Temporal free to run on my own server?
- The Temporal server is published under the MIT licence, so running it yourself carries no licence fee. What you pay for is the machine and your own time running the database, upgrades and security. Self-hosted Temporal leaves out role-based access control and audit logging, so plan for those if you need them.
- Can PostgreSQL handle both persistence and search?
- Yes, from server 1.20 onward PostgreSQL 12 or later can serve as the Visibility store as well as the main persistence database. Temporal still recommends Elasticsearch for Visibility in production. A single PostgreSQL instance is a reasonable start for a small install, as long as you size it for both jobs.
- Which port do my workers connect to?
- Workers and clients connect to the Frontend's gRPC port, 7233 by default. The History, Matching and internal Worker services talk to each other on their own ports and should never be reachable from outside. If workers run on other machines, put mTLS with client certificates on the Frontend before you open 7233 to them.
- Can I change the number of history shards later?
- No. The shard count is read on the first start and later changes are ignored. Growing past it means standing up a new Temporal Service and migrating workflows. Choose a value for your expected peak and load-test it early.
- Is the Docker Compose setup good enough for production?
- The project describes its Compose files as intended for local development and testing. They are fine for evaluation if every port is bound to 127.0.0.1 and the default password is changed. For production, Temporal points to Helm charts or to standalone binaries with your own managed database.
- How quickly can I have a server ready for this?
- A racked dedicated server is handed over within 30 minutes of the payment being approved, with your chosen operating system installed. The payment and fraud checks before approval are the part that can take longer. A server built to your own specification takes hours rather than minutes.