Configuration

Before You Start

You need to know whether browsers will use HTTP or HTTPS and which socket and asset paths the application will expose. The quick start provides a complete baseline if you do not yet have an assembled application.

Current Configuration Contract

Scalive does not read environment variables or own process-wide endpoint configuration. The application loads and validates its settings, then constructs one ZioHttpConfig for the LiveView transport:

import java.time.Duration

val transportConfig = ZioHttpConfig(
  signingSecret = requiredSecret,
  sessionMaxAge = Duration.ofDays(7),
  secureCookie = true,
  allowedWebSocketOrigins = Set(WebSocketOrigin.https("example.com"))
).fold(error => throw IllegalArgumentException(error.toString), identity)

val liveRoutes = ZioHttp.routes(application, transportConfig)

All four values are required:

Use the throwing WebSocketOrigin.http and WebSocketOrigin.https constructors for trusted source literals. Parse deployment input through WebSocketOrigin.parse so an invalid value remains in the startup error channel. For example, load a comma-separated set without logging the untrusted value:

def parseOrigins(value: String): Either[String, Set[WebSocketOrigin]] =
  val entries = value.split(",", -1).iterator.map(_.trim).toVector
  if entries.isEmpty || entries.exists(_.isEmpty) then
    Left("SCALIVE_ALLOWED_ORIGINS must contain only non-empty origins")
  else
    entries.zipWithIndex.foldLeft[Either[String, Set[WebSocketOrigin]]](Right(Set.empty)) {
      case (validated, (entry, index)) =>
        for
          origins <- validated
          origin <- WebSocketOrigin.parse(entry).left.map(error =>
                      s"SCALIVE_ALLOWED_ORIGINS entry ${index + 1}: ${error.message}"
                    )
        yield origins + origin
    }

val transportConfig =
  (for
    rawOrigins <- sys.env
                    .get("SCALIVE_ALLOWED_ORIGINS")
                    .toRight("SCALIVE_ALLOWED_ORIGINS is required")
    origins <- parseOrigins(rawOrigins)
    config <- ZioHttpConfig(
                signingSecret = requiredSecret,
                sessionMaxAge = Duration.ofDays(7),
                secureCookie = true,
                allowedWebSocketOrigins = origins
              ).left.map(_.toString)
  yield config).fold(error => throw IllegalArgumentException(error), identity)

When configuration supplies a trusted scheme separately from a dynamic host or port, use httpEither or httpsEither instead.

The policy is a finite exact set. Wildcard hosts, suffix matching, request-derived origins, and custom predicates are intentionally unsupported. Unicode host input is rejected; configure the ASCII/punycode host serialized by the browser. Origins compare by canonical scheme, host, and effective port, so scheme and host case and an omitted default port do not create separate origins. Programmatic http and https constructors also canonicalize equivalent IP literal spellings; WebSocketOrigin.parse requires a browser-serialized origin.

Construct the value once and reuse it. ZioHttp.routes also validates the assembled Live route catalog, rejecting duplicate live-session names and duplicate rendered paths before the server starts.

Share Security With HTTP Handlers

Construct LiveSecurity when ordinary HTTP handlers need the same CSRF, flash, or cookie policy as Live routes:

val security = LiveSecurity(transportConfig)
val liveRoutes = ZioHttp.routes(application, security)

Cookies produced by these helpers are host-only, root-scoped, HttpOnly, and SameSite=Lax. Their Secure attribute comes from secureCookie. The current API does not configure another cookie domain, path, same-site value, or HttpOnly policy.

Use the same LiveSecurity value in checked form handlers and HTTP-to-Live flash redirects. Do not place passwords, access tokens, cookie values, or other secrets inside signed session claims or flash values: a browser can read signed content.

Configure Routes And Assets

The remaining framework choices are made while assembling the application:

Use classpath or directory when Scalive should version one complete relative output tree. Use deploymentClasspath or deploymentDirectory when an external build owns exact final filenames and cache policy through a deployment manifest.

The Scala and JavaScript socket paths must agree:

val application = Live.router
  .withSocketPath(PathCodec.empty / "socket")(
    Routes.home -> HomeLiveView()
  )

const liveSocket = new LiveView.LiveSocket("/socket", Phoenix.Socket, { params })

Use Client setup and static assets for asset sources, versioned paths, deployment manifests, cache policy, and complete browser wiring.

Observe Lifecycle Operations

Pass one LifecycleObserver as the third route argument. The built-in adapter records fixed, low-cardinality ZIO metrics for disconnected renders, joins, mounts, connected turns, failures, queue pressure, and lifecycle termination:

val liveRoutes = ZioHttp.routes(
  application,
  security,
  LifecycleMetrics.observer
)

Use Lifecycle observability for safe custom observers, the complete metric and label contract, exporter verification, cardinality rules, and the boundary between lifecycle and endpoint instrumentation.

Configure The Server Separately

The application and ZIO HTTP own environment-variable names, bind address, port, direct TLS, server request handling, idle timeouts, response compression, and graceful-shutdown timeout. Configure those through ZIO HTTP's Server.Config or the application's preferred configuration library; they are not fields of ZioHttpConfig.

Public URL generation and trusted-proxy policy remain application concerns. Validate a public URL when the application needs to generate absolute URLs. WebSocket origin admission is instead transport configuration: every upgrade must contain exactly one valid Origin matching allowedWebSocketOrigins. Missing, null, malformed, duplicate, combined, or mismatched values receive HTTP 403 before upgrade. Scalive never derives origin trust from Host, Forwarded, X-Forwarded-Host, X-Forwarded-Proto, or an external URL prefix; do not use those untrusted headers to decide whether cookies are secure either.

Load and validate all application settings once at startup, before StaticAssets.load, route assembly, and Server.serve. Missing secrets, invalid ports, and absent configured assets should stop the process rather than leave a partially configured instance serving traffic.

Scalive supplies no central setting for health routes, cluster membership, shared LiveView state, or transport fallback. Add endpoint-level HTTP instrumentation as application middleware and use LifecycleObserver for LiveView operations. Scalive supports WebSocket transport only; deployment and scaling consequences are covered in Deployment.

Related Tasks

• Continue with Deployment to package and operate the application.

• Use Client setup and static assets to configure browser, socket, and asset paths.

• Publish and interpret LiveView metrics with Lifecycle observability.

• Use Troubleshooting when the HTTP render succeeds but the WebSocket does not join.