Skip To Content

Getting Started

Install the server and connect a .NET client.

develop Unreleased
View source on GitHub

This guide walks through running a squirix server and connecting a .NET client.

Prerequisites:

  • .NET 10 SDK for applications consuming the NuGet packages.
  • Building repository sources uses the SDK pinned in global.json (currently .NET 11 preview).
  • Docker Desktop with Linux containers for the Docker examples; the client example requires Compose 2.17 or newer.
  • For local HTTPS (tests, benchmarks, examples; not Docker): dotnet dev-certs https --trust

1. Run a development server

NuGet global tool

dotnet tool install --global squirix.server.tool --version 0.1.0-preview.10
squirix-server run

The host listens on https://localhost:5001 by default (loopback bind), runs as an in-memory cache, and prints ready-to-use client and operational endpoint URLs. No JWT is required on this default URL — any local process can access the cache API. This is a development convenience, not production hardening. See server-mode.md — Loopback development default.

For journal/snapshot durability:

squirix-server run --persist --data-dir data

Health probes use the same HTTPS listener (local tool default port 5001):

curl https://localhost:5001/health
curl https://localhost:5001/metrics

/metrics is anonymous on loopback when auth is not configured.

If the server cannot bind to port 5001, or the client reports a TLS chain error such as PartialChain, check that the CLI started successfully and that the endpoint belongs to that process. A container or another server already using the port may answer the health probe with a different certificate. If port 5001 is in use, start the CLI with squirix-server run --urls https://localhost:5443 (if 5443 is free), then use that URL in the health probes and the client example. Keep TLS verification enabled.

Docker (fastest if you have Docker Desktop)

Development only. Examples below use the public test JWT key ZGV2LXNxdWlyaXgtZG9ja2VyLWp3dC1rZXkhISEhISE= and bundled dev HTTPS/mTLS certificates. Do not reuse them outside a local machine. See containerization.md.

Single-container examples start in the default ephemeral mode (in-memory cache). The three-node docker compose example enables persistence with --persist --data-dir /data and named volumes.

docker build -f docker/Dockerfile -t squirix-server .
docker run --rm \
  -p 5000:5000 \
  -e SQUIRIX_JWT_SIGNING_KEY=ZGV2LXNxdWlyaXgtZG9ja2VyLWp3dC1rZXkhISEhISE= \
  -e SQUIRIX_JWT_ISSUER=https://squirix.docker.dev \
  -e SQUIRIX_JWT_AUDIENCE=squirix \
  squirix-server run --urls https://0.0.0.0:5000

Port 5000 is the primary HTTPS listener (gRPC, /health, /metrics). Images ship a bundled development HTTPS certificate; use curl -k from the host. When JWT is configured, pass a bearer token for /metrics scrapes from outside the container.

Release image (NuGet tool; Dockerfile default SQUIRIX_VERSION matches the published package):

docker build -f docker/Dockerfile.release -t squirix-server:release .
docker run --rm \
  -p 5000:5000 \
  -e SQUIRIX_JWT_SIGNING_KEY=ZGV2LXNxdWlyaXgtZG9ja2VyLWp3dC1rZXkhISEhISE= \
  -e SQUIRIX_JWT_ISSUER=https://squirix.docker.dev \
  -e SQUIRIX_JWT_AUDIENCE=squirix \
  squirix-server:release run --urls https://0.0.0.0:5000

Three-node RF=3 cluster (docker compose up -d --build in docker/): nodes A, B and C on https://localhost:5001, https://localhost:5002 and https://localhost:5003 (host ports map to container 5000). See containerization.md.

From this repository

dotnet run --project src/squirix.server.host/Squirix.Server.Host.csproj -- run

2. Add the client SDK

dotnet add package squirix --version 0.1.0-preview.10

3. Connect and use a typed cache

Use the HTTPS gRPC endpoint from the host output.

Local tool or dotnet run (default https://localhost:5001, no JWT unless you configure auth):

using System;
using System.Threading;
using Squirix.Client;

var cancellationToken = CancellationToken.None;

await using var client = await SquirixClient.ConnectAsync(new Uri("https://localhost:5001"), cancellationToken);

var cache = await client.GetCacheAsync<string>("demo", cancellationToken);
await cache.SetAsync("greeting", "hello", cancellationToken: cancellationToken);

var lookup = await cache.GetValueAsync("greeting", cancellationToken);
Console.WriteLine(lookup.Found ? lookup.Value : "<missing>");

Expected output: hello.

Docker Compose: use the complete client example. It generates a short-lived development JWT and trusts the cluster's HTTPS certificate only inside its own container. From the repository root, start the three nodes, wait for Server is ready in their logs, then run the client:

docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml -f docker/docker-compose.client.yml run --rm --build --no-deps client

Expected output: Found=True; Value=hello from Docker. For a reproducible leader-crash scenario, see the failover demo. The client connects to Compose DNS names on port 5000. Host applications instead use the published ports 5001–5003, options.BearerTokenProvider, and a properly trusted server certificate. The public client has no certificate-validation override option; do not disable TLS verification. See HTTPS in containers.

Multiple bootstrap endpoints (HA front door, not shards):

using System;
using Squirix.Client;

await using var client = await SquirixClient.ConnectAsync(
    options =>
    {
        options.Endpoints.Add(new Uri("https://cache-a.example.internal:5001"));
        options.Endpoints.Add(new Uri("https://cache-b.example.internal:5002"));
    },
    cancellationToken);

See bootstrap client failover and configuration.

CLI reference

squirix-server init [--settings ./Squirix.settings.json]
squirix-server validate-config --settings ./Squirix.settings.json [--strict]
squirix-server doctor [--settings ./Squirix.settings.json] [--strict]
squirix-server version

run accepts --urls, --persist, --data-dir (with --persist), --settings, and --strict. Without --settings, the host discovers Squirix.settings.json or squirix.settings.json in the working directory and application directory.

Next steps