---
title: Specifications
description: >-
  The store is responsible for managing data persistence such as certificate
  storage, key management, and data replication between multiple nodes/replicas
  of proksi.
---
> ## 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.

## Table of Contents

- [Overview](#overview)
- [Store](#store)
- [DragonflyDB / Redis](#dragonflydb--redis)

## Overview
This document provides a comprehensive specification for the proxy server, covering its architecture, design principles, and implementation details. It serves as a reference for developers working on the project and ensures consistency across different components.

## Store

The store is responsible for managing data persistence such as **certificate** storage, key management, and data replication between multiple nodes/replicas of `super`.

### DragonflyDB / Redis
You can run a local instance of DragonflyDB or Redis using Docker:

```bash
docker run -p 6379:6379 --ulimit memlock=-1 docker.dragonflydb.io/dragonflydb/dragonfly
```

This can be used for development and testing purposes.

### Store keys

The following keys are used by the Redis store (see [ADR 0001](/adrs/0001-route-sources) for routes):

| Key | Description | Content |
| --- | ----------- | ------- |
| `proksi:cert:<domain>` | Certificate for a domain | `{ "key": "...", "leaf": "...", "chain": "..." }` (base64-encoded PEM) |
| `proksi:challenge:<domain>` | ACME challenge for a domain (TTL: 300 seconds) | `["<token>", "<proof>"]` |
| `proksi:route:<host>` | A host (lowercase name) | `{ "schema_version": 2, "host": { "name": "...", "listen": [], "tls": { ... }, "locations": [ ... ] } }` (entries with `schema_version: 1` and a `route` are still read) |
| `proksi:routes` | Set of hosts that have a route | set of `<host>` |
| `proksi:revision` | Revision of the routes, incremented on every change | integer |
| `proksi:replica:<id>` | Revision applied by each proksi instance (TTL: 3 sync intervals) | `{ "id": "...", "revision": 1, "applied_at": 1700000000, "version": "...", "hostname": "..." }` |
| `proksi:certificates:revision` | Revision of the certificates, incremented on every certificate written | integer |
| `proksi:lock:<name>` | Lease held by an instance (`acme:<domain>`, `acme:account`), see [ADR 0002](/adrs/0002-certificate-issuance) | `<id>` of the instance (expires) |
| `proksi:room:{<room>}:active` | Visitors of a [waiting room](/plugins/waiting-room) holding a slot (expires with the room) | sorted set of `<visitor>`, by when the slot expires (milliseconds) |
| `proksi:room:{<room>}:queue` | Visitors waiting in line | sorted set of `<visitor>`, by ticket |
| `proksi:room:{<room>}:seen` | When waiting visitors last checked | sorted set of `<visitor>`, by time (milliseconds) |
| `proksi:room:{<room>}:next` | The last ticket given | integer |
| `proksi:waiting-room:key` | The key waiting rooms' cookies are encrypted with, set once | 64 hex characters |

When changing routes directly in Redis, change `proksi:route:<host>`, `proksi:routes` and `proksi:revision` in a single transaction (`MULTI`/`EXEC`), otherwise replicas won't see the change. The same goes for certificates: change `proksi:cert:<domain>` with `INCR proksi:certificates:revision`.