Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/pingora/llms.txt

Use this file to discover all available pages before exploring further.

A Pingora server is a regular, unprivileged, multithreaded process. It doesn’t require a special supervisor or init system to run — it manages its own lifecycle, signal handling, and zero-downtime upgrades internally. The entry point is the Server struct, which owns all services, handles OS signals, and coordinates shutdown or upgrade sequences.

​
Starting the Server

The minimal bootstrap sequence is three function calls: create the server, bootstrap it, then run it forever. 
use pingora::server::Server;
use pingora::server::configuration::Opt;

fn main() {
    // Pass None to use defaults, or Opt::parse_args() to read CLI flags
    let mut my_server = Server::new(None).unwrap();
    my_server.bootstrap();
    my_server.run_forever()
}
By default, the server runs in the foreground and logs to stderr. Calling run_forever() blocks the current thread indefinitely — it is the last statement in main(). The function may fork the process when daemonization is enabled (see Daemonization), so any threads you create before run_forever() may be lost.

​
Enabling CLI Argument Parsing

Pass Opt::parse_args() to Server::new() to let Pingora read its standard command-line flags at startup: 
use pingora::server::Server;
use pingora::server::configuration::Opt;

fn main() {
    let opt = Opt::parse_args();
    let mut my_server = Server::new(Some(opt)).unwrap();
    my_server.bootstrap();
    my_server.run_forever()
}

​
CLI Arguments

ArgumentEffectDefault
-d, --daemonDaemonize the server (run in the background)false
-t, --testTest the server configuration and then exitfalse
-c, --confPath to the YAML configuration fileempty string
-u, --upgradeStart as a graceful upgrade of a running serverfalse
The -t / --test flag is a work in progress. When set, calling server.bootstrap() exits the process without errors, which is useful for verifying that the new binary can start cleanly before you send SIGQUIT to the running server.

​
Stopping the Server

A running Pingora process responds to three Unix signals, each with different shutdown semantics.

​
SIGINT — Fast Shutdown

Sent by pressing Ctrl+C in a terminal. The server exits immediately with no delay. All in-flight requests are interrupted and their sockets are closed. This is the fastest way to stop a server but is the least graceful, because clients may receive connection resets mid-request. 
# From the terminal running the server:
^C
# Or from another shell:
kill -SIGINT <pid>

​
SIGTERM — Graceful Shutdown

The server notifies all its services to stop accepting new connections, then waits for a preconfigured grace period before exiting. Requests that complete within that window finish normally; any still in-flight after the timeout are interrupted. 
kill -SIGTERM <pid>
# or equivalently
pkill -SIGTERM my_pingora_binary
This is the standard signal used by process managers and systemctl stop.

​
SIGQUIT — Graceful Upgrade

Similar to SIGTERM in that the old server drains gracefully, but SIGQUIT also transfers all listening sockets to a newly started server instance before draining. This means the listening socket is never closed from the client’s perspective, producing zero dropped connections during a binary upgrade. 
kill -SIGQUIT <pid>
# or
pkill -SIGQUIT my_pingora_binary
See the Graceful Upgrade guide for the full step-by-step procedure.

Build docs developers (and LLMs) love

Get started for freeTalk to us