On this page
DEPLOYMENT & APPLICATION REFERENCE
Everything behind
your first write.
Find the setting, connect a client, or plan your deployment. Start with the task in front of you.
Thunder ships as thunderstrike. Commands and environment variables use that distribution name. This reference follows the product guide and the published 0.1.6 release.
8 reference sections
01 / HOST REQUIREMENTS
Prepare the host.
- Docker with Compose v2. The host or Docker Desktop Linux VM must run Linux kernel 6.8 or newer. The server checks this at startup.
- x86-64: AVX2-capable CPUs, such as Intel Haswell or AMD Zen 1 and newer. The standard image targets x86-64-v3. The separate
-v4tag requires AVX-512. - ARM64: ARMv8.2 with Crypto Extensions. The standard ARM image targets hardware such as Graviton2 or newer and Ampere Altra.
- Memory: resident arena memory plus process overhead. For the default two-core budget, plan at least 4 GiB of arena RAM plus overhead.
- Filesystem: ext4 or XFS under Docker’s data directory. Use a named volume on Docker Desktop to avoid its host-file-sharing path.
The release kit configures the io_uring seccomp allowance and memory-lock limit. When running outside Compose, supply the documented security profile, memlock allowance, and persistent data volume yourself.
02 / CONFIGURATION REFERENCE
Start with .env.
Compose reads .env beside compose.yaml; shell environment variables take precedence. Sizes are plain byte counts, without suffixes: use 4294967296 for 4 GiB.
| Variable | Default | Purpose |
|---|---|---|
THUNDERSTRIKE_IMAGE | Release tag in the kit | Image used by the Compose services. Keep it pinned to the intended release. |
THUNDERSTRIKE_CORES | 2 | Even physical-core budget, from 2 through 1,024. Reactor count is derived. |
THUNDERSTRIKE_TLS_PORT | 7380 | First reactor’s listening port. Other ports follow consecutively. |
THUNDERSTRIKE_ARENA_BYTES | Automatic | Resident arena bytes per reactor. Empty means 4 GiB with one reactor, or 2 GiB each with multiple reactors. |
THUNDERSTRIKE_BLOB_PREALLOC_BYTES | 0 | Disk preallocation per logical shard. A nonzero value is multiplied by 1,024 for a new database. |
THUNDERSTRIKE_HOST_PASSPHRASE | ./docker/secrets/passphrase | Host file containing the keystore passphrase on one line. |
THUNDERSTRIKE_HOST_TLS_DIR | ./docker/tls | CA and server certificate/key directory. Only server identity files are mounted into the database. |
THUNDERSTRIKE_TLS_NAMES | localhost | DNS names included in the server certificate. Separate names with spaces or commas. |
THUNDERSTRIKE_HOST_DATA | data | Named volume, or a host path such as /srv/thunderstrike. |
Regenerate ports after allocation changes.
After a clean stop, change the core budget, starting port, or available topology, then run:
docker compose -f compose.yaml run --rm configure
docker compose up -dconfigure writes compose.override.yaml with the exact mapping. It refuses to overwrite an override file you authored yourself. Stale or missing generated mappings prevent startup before the stores open.
03 / APPLICATION CLIENTS
One address to connect.
All official client packages use the same compiled core. It discovers the server layout, maintains connections to reactor ports, pipelines requests, and multiplexes large values over TLS 1.3.
| Language | Install or documentation |
|---|---|
| Python | pip install thunderstrike |
| Node.js | npm install @shortsqueeze/thunderstrike |
| Go | go get github.com/TheManhattanProject/thunderstrike-client/[email protected] |
| Rust | cargo add thunderstrike |
| .NET | dotnet add package Thunderstrike |
| Java | io.github.maverick-ai:thunderstrike-client:0.1.3; JDK 22+ |
| PHP | composer require themanhattanproject/thunderstrike-client, then vendor/bin/thunderstrike-install; enable PHP FFI. |
| C / C++ | Headers and native libraries from the client releases. |
Client platforms include Linux x86-64 and ARM64, Windows x86-64, and macOS on Intel and Apple silicon. Server and client release numbers are independent. Consult the client README for platform and packaging details.
Python: write a session snapshot.
Run from the release-kit directory after the server is healthy. The CA file must be the one that issued the server’s certificate.
from thunderstrike import Thunderstrike
with open("docker/tls/ca.crt") as ca:
ca_pem = ca.read()
db = Thunderstrike(
"127.0.0.1:7380",
tls_server_name="localhost",
tls_ca_pem=ca_pem,
)
db.set(b"agent:42:state", b'{"step": 4}')
state = db.get(b"agent:42:state")
print(state) # bytes; None if the key is missingNode.js: the same connection model.
import { ThunderstrikeClient } from "@shortsqueeze/thunderstrike";
import { readFileSync } from "node:fs";
const db = await ThunderstrikeClient.connect({
endpoints: ["127.0.0.1:7380"],
tlsServerName: "localhost",
tlsCaPem: readFileSync("docker/tls/ca.crt"),
});
await db.set(Buffer.from("agent:42:state"), Buffer.from('{"step": 4}'));
const state = await db.get(Buffer.from("agent:42:state"));
console.log(state); // Buffer; null if the key is missingHandle errors by their retry class.
The client reports a numeric error code and retry class. Busy responses that did not apply a request can be retried. A lost connection or timeout can leave the outcome unknown: retry only when the operation is safe to repeat. The client already retries some busy answers and dropped connections internally; see its documented retry behavior before adding application retries.
Thunder uses its own protocol. Redis clients cannot connect directly. Values are opaque bytes; schema interpretation, authorization, search, and automatic expiration belong in your application.
04 / SHARDS & PORTS
Let the client find the owner.
The server always has 1,024 logical shards. The client requests DISCOVER, hashes each key using CRC32C(key) % 1024, and sends its request to the owning reactor.
- Each reactor owns a contiguous shard range, one arena, and one port.
- For
Rreactors, each receivesfloor(1024 / R)shards. The first1024 % Rreactors receive one additional shard. - Ports start at
THUNDERSTRIKE_TLS_PORTand increase by reactor index. - Expose every generated port on the same host and port number. Port translation that changes the discovered number breaks routing.
- The persisted routing epoch advances when ownership or ports change.
Two usable hardware threads per physical core produce one reactor group per core. Without SMT, two physical cores supply one group. Actual topology, affinity, and quotas determine the allocation.
05 / CAPACITY PLANNING
Size memory per reactor.
The arena is resident from boot. Container limits must exceed arena bytes multiplied by the derived reactor count, with additional headroom for the process.
| Example | Arena per reactor | Total arena RAM |
|---|---|---|
| 2 cores, no SMT, automatic arena | 4 GiB × 1 reactor | 4 GiB + process overhead |
| 2 cores, SMT ×2, automatic arena | 2 GiB × 2 reactors | 4 GiB + process overhead |
| 8 cores, SMT ×2, 512 MiB values | 4 GiB × 8 reactors | 32 GiB + process overhead |
Large writes need working room.
A SET needs two copies of its value in the arena. For 512 MiB values, explicitly configure THUNDERSTRIKE_ARENA_BYTES=4294967296. Concurrent requests and the mix of sizes also affect practical capacity.
Reserve space beyond the live bytes.
The documented disk-sizing rule is peak live bytes / 0.75, plus one 4 GiB chunk when storing values of 512 MiB or more. For 300 GiB of live values with such objects, that gives 404 GiB. Plan backup storage separately.
Files grow as needed with the default preallocation of zero. A nonzero preallocation setting applies to every logical shard. When the volume fills, writes return StorageExhausted and reads continue to be served.
06 / TLS & ENCRYPTION
Protect the connection and the store.
TLS 1.3 is mandatory. The server requires an Ed25519 certificate issued by a CA, a matching key, and valid certificate dates. A self-signed server identity is refused.
The files and who needs them.
| File | Purpose | Access |
|---|---|---|
ca.crt | Issuing CA certificate | Distribute to clients so they can verify the server. |
ca.key | CA signing key | Keep private and backed up. Do not mount into the database. |
server.crt | Server identity and DNS names | Mount read-only into the server. |
server.key | Server private key | Only the server needs it. |
tls-init creates the CA and server identity. Set THUNDERSTRIKE_TLS_NAMES before generating the identity. Clients must connect using a name on the certificate and trust the CA. Keep localhost among the names when using the bundled sample.
Renew without replacing the CA.
Keep the CA files. Remove the old server certificate and key from the TLS directory, run docker compose run --rm tls-init, then recreate the server container. The job does not overwrite existing identity files. Clients continue trusting the same CA.
Use your own CA or mutual TLS.
You can provide an Ed25519 CA and key to tls-init, or provide a server certificate chain and key yourself. Every certificate in the chain must use Ed25519. To require client identities, mount a client CA and set THUNDERSTRIKE_TLS_CLIENT_CA to its container path.
Keep the keystore passphrase with your backup plan.
Every value is encrypted at rest. The passphrase unlocks the keystore; there is no default passphrase. Losing the passphrase or data volume loses access to the values. A wrong passphrase prevents startup with Kek(AuthFailed).
07 / OPERATE & RECOVER
A clean stop is part of the workflow.
docker compose ps
docker compose logs --tail=100 thunderstrikeHealthy means every derived reactor has completed recovery and is listening. Startup can take time while arenas become resident and stores recover.
Stopping
docker compose stop thunderstrike sends SIGTERM. The server stops accepting requests, drains in-flight work, checkpoints the index, and exits. The kit allows two minutes. A forced kill is a crash.
Backups
- Stop the server, or use an appropriate filesystem snapshot.
- Copy the entire data volume, including the keystore.
- Preserve the passphrase securely with the backup plan.
- Keep the original backup intact while validating a restore on a separate deployment.
A file copy made while the database is writing is not consistent. Follow the complete backup procedure in the product guide.
Upgrades
Back up first. Extract the new release kit, carry over the deployment settings and secret/TLS files, set the new image reference, and start it against the preserved data volume. The named data volume is independent of the kit directory.
Topology changes after a crash
Recover using an allocation that produces the previous reactor count, then stop cleanly before changing it. Reactor journals belong to reactors. After a clean stop and configuration change, rerun configure before starting.
Durability
Every acknowledged write has a journal record on disk before the acknowledgement. The product guide’s durability contract covers crashes and power cuts. An orderly stop loses no acknowledged writes.
08 / TROUBLESHOOTING
Start with the first refusal.
If Compose repeatedly restarts the server, inspect docker compose logs thunderstrike. The first startup refusal usually identifies the setting to fix.
| Symptom | Check |
|---|---|
io_uring not supported | Host kernel must be 6.8+. Use the release kit’s io_uring-enabled seccomp profile. |
RLIMIT_MEMLOCK too low | Use the kit’s memlock allowance. Check the Docker daemon’s own limits if the container cannot set them. |
| Container memory below resident arena | Budget arena bytes × derived reactors, plus overhead. Increase the limit or reduce the allocation. |
no keystore passphrase | The configured file must exist, be readable, and contain the passphrase. |
Kek(AuthFailed) | Use the passphrase associated with this volume’s keystore. |
| Certificate verification fails | Verify the trusted CA, DNS name, certificate dates, and Ed25519 chain. |
| First port works; later connections fail | Expose every discovered reactor port using the same host and container port numbers. |
| Published ports missing or stale | After a clean stop, rerun configure and then restart. |
| Physical-core budget refused | Use an even budget from 2 through 1,024 within the available physical CPUs and quota. |
| Previous reactor count required | Recover with the previous allocation, stop cleanly, then change topology. |
| Exit status 132 / SIGILL | The CPU may not support the image’s instruction set. In particular, -v4 requires AVX-512. |
StorageExhausted | The volume is full. Provision sufficient space; the server continues serving reads. |
| Exactly 1,024 shards required | The directory uses another routing modulus. Migrate into a new store; do not edit the on-disk count record. |
| A size is not a plain integer | Use bytes without unit suffixes. Four GiB is 4294967296. |
Reference sources: the product guide, release-kit settings, and the official client documentation.
No matching section.
Try a shorter term such as “TLS”, “ports”, or “memory”, or clear the search to see the full reference.