---
title: Restarts and upgrades
description: >-
  Hosts (host blocks, routes, docker labels, the store, Kubernetes) are applied
  while Super runs.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.page/luizfonseca/super/llms.txt
> Use this file to discover all available pages before exploring further.

Hosts (`host` blocks, `routes`, docker labels, the store, Kubernetes) are applied while Super runs. Everything else (listening addresses, `server`, `logging`, `store`, ...) is read at startup, so changing it needs a new Super process. On Linux, that new process takes over without dropping a connection.

## How it works (Linux)

Super runs as two kinds of processes:

- a **supervisor**, the process you start (PID 1 in a container), which only starts and replaces the others;
- a **worker**, started by the supervisor, which serves every request.

To upgrade, the supervisor starts a new worker, and the current one hands its listening sockets over to it:

1. The new worker loads the configuration and receives the listening sockets: no port is closed, and no connection is refused.
2. It starts accepting connections once its routes are applied (and, while upgrading, the certificates of its hosts loaded), for up to 10 seconds.
3. The previous worker accepts new connections for a few more seconds, then stops accepting and lets its open connections finish: requests in progress, websockets, `tcp` connections. It stops as soon as they're closed, or after `server.shutdown_timeout_secs` (30 seconds by default), closing what's left.

Addresses removed from the configuration are closed once the previous worker stops.

An upgrade happens:

- when the configuration changes, with [auto reload](/configuration/auto-reload), and settings other than hosts changed;
- when the supervisor receives `SIGHUP`. It starts the new worker from the binary and configuration on disk, so it's also how to move to a new version of Super in place:

```bash
cp proksi-new /usr/local/bin/proksi
kill -HUP <supervisor pid>          # or: systemctl reload proksi, docker kill -s HUP <container>
```

An invalid configuration is refused before anything is replaced: the current worker keeps running, and the reason is logged. An upgrade asked for while a new worker is still starting follows once it's ready.

## Stopping

`SIGTERM` (`docker stop`, Kubernetes, `systemctl stop`) and `SIGINT` (Ctrl-C) are passed to the workers, which stop accepting and let their connections finish, for up to `server.shutdown_timeout_secs`. The supervisor exits once they have. Give the platform a little longer than that timeout before it kills Super:

| Platform | Setting |
| --- | --- |
| Docker Compose | `stop_grace_period: 35s` |
| `docker stop` | `docker stop -t 35` |
| Kubernetes | `terminationGracePeriodSeconds: 35` (set in the manifest and the helm chart) |
| systemd | `TimeoutStopSec=35` |

## systemd

```ini
[Service]
ExecStart=/usr/local/bin/super -c /etc/proksi
ExecReload=/bin/kill -HUP $MAINPID
TimeoutStopSec=35
```

The supervisor is the main process, so systemd keeps tracking the service while workers are replaced.

## Kubernetes

In Kubernetes, configuration changes usually reach Super as a new pod: the helm chart restarts the pods when its `ConfigMap` changes, one at a time, and each stops as above. Upgrades in place apply when `auto_reload` is enabled and the mounted configuration changes.

## Logs

Workers log as configured in `logging`. The supervisor writes a line to stderr when it starts a worker and when one stops (`proksi supervisor: worker 41 stopped (exit code 0)`).

## Other platforms

The listening sockets can only be handed over on Linux. Elsewhere (macOS, or with `--daemon`), there's no supervisor: a settings change restarts Super in place, and its open connections are closed.

The socket used for the handover is in the temporary directory (`proksi-upgrade-<id>.sock`), one per configuration path, so several Super instances can run on the same machine.