How temporalio/ui-server works
Purpose and Entrypoint
This repository packages Temporal’s UI server: a Go HTTP service that serves a prebuilt UI and proxies UI API calls to a Temporal gRPC endpoint. The executable starts at cmd/server/main.go; server assembly and lifecycle are centered in server/server.go.
Startup and Configuration
Configuration is modeled and validated by server/config/config.go, with provider abstractions in server/config/config_provider.go. The filesystem plugin loads YAML configuration (plugins/fs_config_provider/fs_config_provider.go), using deployment variants such as config/base.yaml, config/docker.yaml, and config/with-auth.yaml. A refresh-capable provider (server/config/config_provider_with_refresh.go) creates a boundary between server runtime and dynamic configuration sources.
HTTP Edge and Route Composition
The HTTP-facing server organizes routes by concern: API forwarding in server/route/api.go, authentication endpoints in server/route/auth.go, health checks in server/route/health.go, and UI/static routing in server/route/ui.go. This is the primary request dispatch boundary: browser and operational traffic arrive over HTTP, then are classified as static UI, health, auth, or Temporal API requests.
API Gateway and Temporal RPC Boundary
server/api/handler.go implements API request handling; server/api/marshaler.go controls HTTP payload translation and server/api/rawhistory.go supports raw workflow-history responses. Requests crossing this layer are sent through the RPC client layer in server/rpc/rpc.go, with TLS setup in server/rpc/tls.go. The material external dependency is a Temporal gRPC service, particularly the WorkflowService API referenced by the README.
Identity and Browser Security
Optional authentication is defined by server/auth/auth.go and OpenID Connect integration by server/auth/oidc.go; auth configuration is isolated in server/config/auth.go. Cross-origin policy is enforced by server/cors/cors.go, while CSRF protections—including cookie handling and request-origin checks—live in server/csrf/cookie.go and server/csrf/sec_fetch_site.go. These layers protect browser-to-server requests before they reach API/RPC handling.
UI Delivery
The UI is compiled static content embedded into the Go binary via ui/embed.go, sourced from ui/assets/local/index.html and its generated _app bundles. server/route/ui.go serves this embedded application, including public-path behavior handled by server/route/public_path.go. The repository contains artifacts rather than UI source, so UI behavior is built elsewhere and delivered here as versioned static assets.
Deployment Model
The service is containerized by Dockerfile; docker/start-ui-server.sh is the container startup wrapper. GitHub Actions build/download the UI and build/push images through .github/actions/download-and-build-ui/action.yaml and .github/actions/docker-build-push/action.yml. The runtime is therefore a Go server plus embedded frontend, configured externally through YAML and connected to Temporal over gRPC/TLS.
Main entry points: api.go HTTP route composition · server.go Server lifecycle · config_provider_with_refresh.go Refreshable config provider · main.go Server executable
Components 18
Go Server
HTTP service and Temporal gateway.
- Server executable
cmd/server/main.go - Server lifecycle · Builds and runs the HTTP server.
server/server.go - Configuration model
server/config/config.go - Refreshable config provider · Insulates the server from dynamic configuration sources.
server/config/config_provider_with_refresh.go - YAML config loader
plugins/fs_config_provider/fs_config_provider.go - Deployment YAML · Base, Docker, and auth deployment variants.
config/base.yaml - HTTP route composition · Classifies UI, health, auth, and API traffic.
server/route/api.go - API gateway · Translates UI API requests and raw history responses.
server/api/handler.go - Temporal RPC client · Connects to Temporal with TLS support.
server/rpc/rpc.go
Browser Security
Optional identity and request protections.
- OIDC authentication · Optional authentication endpoints and flow.
server/auth/oidc.go - Auth configuration
server/config/auth.go - CORS policy
server/cors/cors.go - CSRF protection · Cookie and request-origin protections.
server/csrf/cookie.go
UI & Deployment
Embedded UI assets and container delivery.
- UI static routes · Serves the embedded application and public paths.
server/route/ui.go - Embedded UI assets · Prebuilt frontend bundled into the Go binary.
ui/embed.go - Container startup · Starts the UI server in the image.
docker/start-ui-server.sh
Other components
- Browser / operators
- Temporal WorkflowService
Connections 17
- Browser / operators → CORS policy: HTTP requests
- CORS policy → CSRF protection: browser policy
- CSRF protection → HTTP route composition: protected requests
- Server executable → Server lifecycle: starts
- Server lifecycle → Refreshable config provider: reads runtime config
- Refreshable config provider → Configuration model: validates
- Refreshable config provider → YAML config loader: loads from
- YAML config loader → Deployment YAML: reads
- Server lifecycle → HTTP route composition: mounts
- HTTP route composition → API gateway: API requests
- HTTP route composition → OIDC authentication: auth endpoints
- HTTP route composition → UI static routes: UI and static requests
- OIDC authentication → Auth configuration: uses
- API gateway → Temporal RPC client: translated calls
- Temporal RPC client → Temporal WorkflowService: gRPC/TLS
- UI static routes → Embedded UI assets: serves
- Container startup → Server executable: launches