temporal-server start

Start the Temporal Server

The temporal-server start command starts one or more Temporal Server services.

Synopsis

temporal-server start [flags]

Description

Starts Temporal Server with the specified services. By default, starts all four core services:

• frontend: Public-facing API service
• history: Workflow execution orchestration
• matching: Task queue management and distribution
• worker: System workflows (archival, replication, etc.)

Optionally, you can also run:

• internal-frontend: Internal API service for admin operations

Options

—service, —svc

Specifies which service(s) to start. Can be specified multiple times.

• Type: String (repeatable)
• Default: frontend, history, matching, worker
• Valid values: frontend, history, matching, worker, internal-frontend

# Start all services (default)
temporal-server start

# Start only frontend and history
temporal-server start --service frontend --service history

# Start with internal-frontend for admin operations
temporal-server start --service frontend --service history --service matching --service worker --service internal-frontend

—config-file

Path to the configuration file.

• Type: String (file path)
• Default: None (uses embedded configuration)
• Environment variable: TEMPORAL_SERVER_CONFIG_FILE_PATH

temporal-server start --config-file /etc/temporal/config.yaml

Note: Cannot be used with --config, --env, --zone, or --root.

—allow-no-auth

Allows the server to start without an authorizer configured.

• Type: Boolean
• Default: false
• Environment variable: TEMPORAL_ALLOW_NO_AUTH

temporal-server start --allow-no-auth

Warning: Only use in development environments. Production deployments should always use proper authorization.

Deprecated Options

The following options are deprecated. Use --config-file instead.

—root, -r

Root directory of execution environment.

• Type: String
• Default: .
• Environment variable: TEMPORAL_ROOT
• Deprecated: Use --config-file

—config, -c

Config directory path relative to root.

• Type: String
• Default: config
• Environment variable: TEMPORAL_CONFIG_DIR
• Deprecated: Use --config-file

—env, -e

Runtime environment.

• Type: String
• Default: development
• Environment variable: TEMPORAL_ENVIRONMENT
• Deprecated: Use --config-file

—zone, —az

Availability zone.

• Type: String
• Default: None
• Environment variable: TEMPORAL_AVAILABILITY_ZONE
• Deprecated: Use --config-file

—services, -s

Comma-separated list of services (legacy format).

• Type: String
• Deprecated: Use --service flag multiple times instead

# Old format (deprecated)
temporal-server start --services frontend,history,matching

# New format (recommended)
temporal-server start --service frontend --service history --service matching

Examples

Start with Default Configuration

Uses embedded development configuration:

temporal-server start

Start with Custom Configuration

temporal-server start --config-file /etc/temporal/production.yaml

Start Specific Services

Run only frontend and history on separate hosts:

# On host 1
temporal-server start \
  --config-file /etc/temporal/config.yaml \
  --service frontend \
  --service history

# On host 2  
temporal-server start \
  --config-file /etc/temporal/config.yaml \
  --service matching \
  --service worker

Development Mode

Start with no authentication for local development:

temporal-server start --allow-no-auth

Using Environment Variables

export TEMPORAL_SERVER_CONFIG_FILE_PATH=/etc/temporal/config.yaml
export TEMPORAL_ALLOW_NO_AUTH=false
temporal-server start

Docker Deployment

FROM temporalio/server:latest

COPY config.yaml /etc/temporal/config.yaml

CMD ["temporal-server", "start", "--config-file", "/etc/temporal/config.yaml"]

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: temporal-frontend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: temporal-frontend
  template:
    metadata:
      labels:
        app: temporal-frontend
    spec:
      containers:
      - name: temporal
        image: temporalio/server:latest
        args:
        - "start"
        - "--service"
        - "frontend"
        - "--config-file"
        - "/etc/temporal/config.yaml"
        ports:
        - containerPort: 7233
          name: grpc
        - containerPort: 7243
          name: http
        volumeMounts:
        - name: config
          mountPath: /etc/temporal
      volumes:
      - name: config
        configMap:
          name: temporal-config

Service Roles

Frontend Service

• Handles client API requests
• Performs authentication and authorization
• Routes requests to internal services
• Exposes both gRPC (port 7233) and HTTP (port 7243) endpoints

History Service

• Manages workflow execution state
• Persists workflow history
• Coordinates workflow task execution
• Handles workflow signals, queries, and updates

Matching Service

• Manages task queues
• Distributes tasks to workers
• Handles task queue partitioning
• Manages worker versioning

Worker Service

• Executes system workflows
• Handles archival of closed workflows
• Manages cross-cluster replication
• Processes background tasks

Internal-Frontend Service (Optional)

• Provides internal APIs for system workers
• Separates internal traffic from external clients
• Recommended for production with authorization

Startup Process

1. Configuration Loading: Loads config from file or embedded defaults
2. Dynamic Config: Initializes dynamic configuration client
3. Authorization: Sets up authorizer, claim mapper, and audience mapper
4. Service Initialization: Starts requested services
5. Health Checks: Services report healthy once initialized
6. Ready to Serve: Server begins accepting requests

Shutdown Behavior

The server handles graceful shutdown on signals:

• SIGTERM: Graceful shutdown with drain period
• SIGINT (Ctrl+C): Immediate shutdown

During graceful shutdown:

1. Stops accepting new requests
2. Drains in-flight requests
3. Closes database connections
4. Exits cleanly

Exit Codes

• 0: Successful shutdown
• 1: Configuration error or startup failure
• 2: Invalid command-line arguments

Troubleshooting

Service Won’t Start

1. Check configuration file syntax:

   temporal-server validate-dynamic-config config/dynamicconfig.yaml
   

2. Verify database connectivity:

   # Test PostgreSQL connection
   psql -h localhost -U temporal -d temporal
   

3. Check port availability:

   netstat -tuln | grep 7233
   

4. Review server logs for errors

Authorization Errors

1. Verify authorizer configuration in config file
2. Check JWT key provider settings
3. Ensure --allow-no-auth is set for development
4. Review authorization logs

Database Connection Issues

1. Verify database credentials
2. Check network connectivity
3. Ensure database schema is initialized:
   temporal-sql-tool --plugin postgres setup-schema -v 0.0
   

Performance Issues

1. Check resource limits (CPU, memory)
2. Monitor database performance
3. Review dynamic config settings
4. Check for network latency

See Also

• temporal-server validate-dynamic-config - Validate dynamic configuration
• temporal-server render-config - Render configuration template
• Server Configuration Reference
• Environment Variables