Installation

The fastest way to evaluate Sockudo is Docker Compose. On Linux, the release installer downloads a verified prebuilt binary. For container platforms, pull the published image from GitHub Container Registry or Docker Hub. Other operating systems can build from crates.io or source.

Docker Compose

git clone https://github.com/sockudo/sockudo.git
cd sockudo
docker compose up sockudo redis

The default server listens on:

Use Compose when you want Redis, local configuration, and repeatable development infrastructure without compiling Rust first.

Install a Linux binary

The installer supports x86_64 and ARM64 Linux, detects GNU libc or musl, and verifies the release archive against its published SHA-256 checksum. It installs to ~/.local/bin by default.

curl --proto '=https' --tlsv1.2 -sSfL \
  https://sockudo.io/install.sh | sh

sockudo.io/install.sh is the stable public URL. It redirects to the installer attached to the latest GitHub release; the installer then downloads and verifies the selected version from GitHub.

Pin the binary version in deployments:

curl --proto '=https' --tlsv1.2 -sSfL \
  https://sockudo.io/install.sh \
  | sh -s -- --version 5.0.1

Choose another writable installation directory with --bin-dir:

curl --proto '=https' --tlsv1.2 -sSfL \
  https://sockudo.io/install.sh \
  | sh -s -- --bin-dir "$HOME/bin"

Run the installed binary with a local configuration file:

sockudo --config ./config/config.toml

Only Linux binaries are published. cargo binstall sockudo remains available for the same Linux release assets; use a source build on macOS, Windows, and other platforms.

Install from crates.io

Use cargo install when you prefer building the published crate on the target host or need a platform without a prebuilt binary:

cargo install sockudo --locked

Pin a release or enable the same production-oriented features you would use from source:

cargo install sockudo --version 5.0.1 --locked
cargo install sockudo --locked --features "redis,postgres,push"

This path compiles on the machine where you run it, so it needs a Rust toolchain and any native libraries required by the selected storage or adapter features.

Pull a container image

Sockudo publishes multi-architecture images to GitHub Container Registry and Docker Hub. GHCR is the primary registry; Docker Hub mirrors the same release tags.

docker pull ghcr.io/sockudo/sockudo:latest
docker pull sockudo/sockudo:latest

Use versioned tags for production rollouts:

docker pull ghcr.io/sockudo/sockudo:5.0.1
docker pull sockudo/sockudo:5.0.1

Start a local container with an in-memory app and Prometheus metrics exposed:

docker run --rm --name sockudo \
  -p 6001:6001 \
  -p 9601:9601 \
  -e HOST=0.0.0.0 \
  -e PORT=6001 \
  -e METRICS_PORT=9601 \
  -e METRICS_ENABLED=true \
  -e SOCKUDO_DEFAULT_APP_ID=demo-app \
  -e SOCKUDO_DEFAULT_APP_KEY=demo-key \
  -e SOCKUDO_DEFAULT_APP_SECRET=demo-secret \
  ghcr.io/sockudo/sockudo:latest

Mount a checked-in configuration file when you need the same settings locally, in CI, and in production:

docker run --rm --name sockudo \
  -p 6001:6001 \
  -p 9601:9601 \
  -v "$PWD/config/config.toml:/app/config/config.toml:ro" \
  ghcr.io/sockudo/sockudo:latest \
  sockudo --config /app/config/config.toml

Run from source

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
git clone https://github.com/sockudo/sockudo.git
cd sockudo
cargo run --release

The default feature set is intentionally local-friendly. Add only the backends your deployment needs:

cargo build --release --features "redis,postgres"
cargo build --release --features "redis-cluster,mysql"
cargo build --release --features "nats,postgres"
cargo build --release --features "kafka,postgres"
cargo build --release --features "iggy,postgres"
cargo build --release --features full

Feature flags

Minimal Pusher-compatible build

If you only need a small Pusher-compatible server, build without default features:

cargo build --release --no-default-features

Add V2 features explicitly when needed:

cargo build --release --no-default-features --features "recovery,delta,tag-filtering"

Configuration file

Sockudo prefers TOML configuration. The server looks for config/config.toml first, with JSON kept as a fallback.

port = 6001
host = "0.0.0.0"
debug = false

[app_manager]
driver = "memory"

[app_manager.array]
[[app_manager.array.apps]]
id = "app-id"
key = "app-key"
secret = "app-secret"
enabled = true

[app_manager.array.apps.policy.limits]
max_connections = 10000

[app_manager.array.apps.policy.features]
enable_client_messages = false

For exact loading precedence, equivalent JSON, secret injection, and clustered examples, see Static configuration.

Kubernetes with Helm

helm install sockudo oci://ghcr.io/sockudo/charts/sockudo --version 4.7.0 \
  --set config.adapterDriver=redis \
  --set redis.host=redis-master \
  --set autoscaling.enabled=true \
  --set pdb.enabled=true \
  --set ingress.enabled=true \
  --set serviceMonitor.enabled=true

Use Kubernetes when you need autoscaling, service monitors, disruption budgets, secret-backed app credentials, and cluster-level rollout controls. Continue with the production Kubernetes and Helm guide.

Verify

curl -f http://127.0.0.1:6001/up
curl -f http://127.0.0.1:9601/metrics | head

When health is green, continue with First connection. Before shipping, follow the Deployment guide.