Skip to content

Server

Under the server config option the (http) server can be configured.

ip_listen

string 0.0.0.0 optional LH_SERVER_IP_LISTEN

The ip_listen config option is used to set the network address to which to bind to. If omitted 0.0.0.0 is used.

config.yaml 
server:
    ip_listen: 127.0.0.1

port

integer 7672 optional LH_SERVER_PORT

The port config option is used to set the port at which LightHouse starts the webserver and listens for incoming requests. Will only be used if tls is not used. If tls is enabled port 443 will be used (and optionally port 80).

config.yaml 
server:
    port: 4242

prefork

boolean false optional LH_SERVER_PREFORK

The prefork option enables multiple processes listening on the same port. When enabled, LightHouse spawns multiple child processes to distribute incoming connections across CPU cores for improved performance.

config.yaml 
server:
    prefork: true

Requirements and Recommendations

We recommend to not enable prefork mode.

If you still want to use prefork mode, consider the following:

Strongly recommended: Use Redis for caching

In prefork mode, each child process has its own in-memory caches (eligibility cache, issued trust mark cache, etc.). This means cache invalidations via the Admin API only affect the process that receives the request. To ensure cache consistency across all processes, it is strongly recommended to configure Redis for caching:

cache:
    redis_addr: "localhost:6379"

Database recommendations

  • SQLite: Not recommended with prefork. Multiple processes writing to SQLite may cause write conflicts.
  • MySQL/PostgreSQL: Recommended for production deployments with prefork enabled.

Background tasks

Background tasks like the proactive resolver and periodic entity collector run only in the parent process to avoid duplicate work.

Admin API

The Admin API server runs only in the parent process when prefork is enabled.

Running in Docker

When using prefork with Docker, ensure the application is started with a shell. Use CMD ./lighthouse or CMD ["sh", "-c", "/lighthouse"] instead of CMD ["/lighthouse"] as prefork mode sets environment variables.

tls

Under the tls config option settings related to tls can be configured. It is unlikely that one enables tls since a reverse proxy will be used in most cases.

If tls is enabled port 443 will be used.

config.yaml 
server:
    tls:
        enabled: true
        redirect_http: true
        cert: /path/to/cert
        key: /path/to/key

enabled

boolean true optional LH_SERVER_TLS_ENABLED

If set to false tls will be disabled. Otherwise, it will automatically be enabled, if cert and key are set.

redirect_http

boolean true optional LH_SERVER_TLS_REDIRECT_HTTP

The redirect_http option determines if port 80 should be redirected to port 443 or not.

cert

file path required for TLS LH_SERVER_TLS_CERT

The cert option is set to the tls cert file.

key

file path required for TLS LH_SERVER_TLS_KEY

The key option is set to the tls key file.

trusted_proxies

list of strings optional LH_SERVER_TRUSTED_PROXIES

The trusted_proxies option is used to configure a list of trusted proxies by IP address or network range (CIDR notation).

If LightHouse runs behind some sort of proxy, like a load balancer, then certain header information may be sent to LightHouse using special X-Forwarded-* headers or the Forwarded header. For example, to forward the client's real IP address.

If set, such header information is only used when the request comes via one of the trusted proxies. If unset, the information is always read from the headers, which might be spoofed.

config.yaml 
server:
    trusted_proxies:
        - "10.0.0.0/8"
        - "172.16.0.0/12"
        - "192.168.0.0/16"
        - "fc00::/7"

# Environment variable (comma-separated)
export LH_SERVER_TRUSTED_PROXIES="10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"

forwarded_ip_header

string X-Forwarded-For optional LH_SERVER_FORWARDED_IP_HEADER

The forwarded_ip_header option specifies which HTTP header to use for getting the client's real IP address when behind a proxy.

config.yaml 
server:
    forwarded_ip_header: X-Real-IP

admin_tls

object / mapping optional LH_API_ADMIN_TLS_

Admin API TLS Configuration

This field is automatically populated from api.admin.tls configuration and does not need to be set manually in the server configuration. See Admin API TLS Configuration for details.

cors

object / mapping optional

Configuration for CORS (Cross-Origin Resource Sharing) on the main server. CORS allows web browsers to make requests to the API from different origins.

This is useful when:

  • Hosting API documentation (like Swagger UI) on a different domain
  • Building web applications that consume the federation endpoints
  • Allowing third-party integrations
config.yaml 
server:
    cors:
        enabled: true
        allow_origins: "*"
        allow_methods: "GET,POST,HEAD,PUT,DELETE,PATCH"
        allow_headers: "Origin,Content-Type,Accept"
        allow_credentials: false
        max_age: 3600

Admin API CORS

The Admin API has its own separate CORS configuration under api.admin.cors. This allows you to have different CORS policies for federation endpoints and admin endpoints.

enabled

boolean false optional LH_SERVER_CORS_ENABLED

Enables or disables CORS middleware for the main server. When disabled, no CORS headers are sent and cross-origin requests from browsers will be blocked.

allow_origins

string * optional LH_SERVER_CORS_ALLOW_ORIGINS

Comma-separated list of allowed origins, or * to allow all origins.

Examples:

  • * - Allow all origins
  • https://example.com - Allow only example.com
  • https://example.com,https://app.example.com - Allow multiple specific origins
config.yaml 
server:
    cors:
        enabled: true
        allow_origins: "https://example.com,https://app.example.com"

allow_methods

string GET,POST,HEAD,PUT,DELETE,PATCH optional LH_SERVER_CORS_ALLOW_METHODS

Comma-separated list of allowed HTTP methods.

allow_headers

string empty (uses Fiber defaults) optional LH_SERVER_CORS_ALLOW_HEADERS

Comma-separated list of allowed request headers. If empty, the Fiber CORS middleware uses sensible defaults.

allow_credentials

boolean false optional LH_SERVER_CORS_ALLOW_CREDENTIALS

Indicates whether the request can include user credentials like cookies, HTTP authentication, or client-side SSL certificates.

Warning

When allow_credentials is true, allow_origins cannot be set to *. You must specify explicit origins.

expose_headers

string empty optional LH_SERVER_CORS_EXPOSE_HEADERS

Comma-separated list of headers that browsers are allowed to access.

max_age

integer 0 optional LH_SERVER_CORS_MAX_AGE

How long (in seconds) browsers should cache preflight request results. A value of 0 means no caching.