Deploy your own CDN across your chosen regions. Start with up to two nodes without a Spook Systems account, then optionally claim your deployment to manage it through the control panel at https://spooksystems.io and upgrade for more nodes and advanced features.
A substrate is a group of authenticated QSCS nodes that share configuration and eligible state. Each node has its own persistent UUID and private key. Using the same upstream URL in two deployments does not give them shared membership.
The free entitlement provides two nodes, one substrate and one origin.
For configuration, concepts and operating guides, see the QSCS documentation.
Use docker.io/spooksystems/qscs:latest on Linux amd64 workers. The image runs as user and group 10001; leave its command and arguments unchanged.
You need persistent storage, DNS resolution, connectivity to your upstream application, and outbound HTTPS (TCP 443) to:
spooksystems.org — enrollment service.monitoring.spooksystems.org — monitoring and telemetry service.Public access also requires an ingress controller and a hostname with a suitable TLS certificate.
Create a StatefulSet with the following settings using your preferred Kubernetes deployment tool.
| Setting | Configuration |
|---|---|
| Image | docker.io/spooksystems/qscs:latest |
| Replicas | Start with 1 or 2 |
| User and group | runAsUser: 10001, runAsGroup: 10001, fsGroup: 10001 |
| Persistent storage | A separate writable volume for each replica, mounted at /var/lib/qscs |
| Storage capacity | Size for your application; 10 GiB per node is an example starting allocation |
| Peer discovery | A headless Service with publishNotReadyAddresses: true and stable per-pod DNS names |
| Application access | A Service forwarding to TCP 8080 |
| Readiness | TCP check on port 8080 |
| Shutdown grace period | 90 seconds |
| Image pull policy | Always to resolve latest when a container starts |
Keep pod names and volume associations stable across restarts and upgrades. A volume contains the node's identity, configuration and saved response state; never share one writable volume between running replicas or copy an enrolled volume to create another node.
The storage driver must make the mount writable by group 10001. If using a read-only container root filesystem, also provide a writable temporary mount at /tmp. Kubernetes StatefulSets, volume permissions
For a new deployment, use auto-cluster. One named replica creates an anonymous account handle and substrate; the other replicas join it using a shared deployment secret.
Generate the secret once per deployment:
openssl rand -hex 32
Store the result as a Kubernetes Secret and mount it read-only in each replica. It must contain 64 lowercase hexadecimal characters; a trailing newline is accepted. Make it readable by the node's service user, for example using mode 0440 with group 10001.
Keep the secret private. Someone who obtains it can request an available node slot while the deployment remains unclaimed and its admission grant is active. It is not used as the peer encryption key. Kubernetes Secret security
Set these environment variables:
| Variable | Value |
|---|---|
QSCS_BOOTSTRAP_MODE | auto-cluster |
QSCS_INITIAL_REPLICA | The exact initializer pod name, such as qscs-0 |
QSCS_REPLICA_NAME | Populate from Kubernetes metadata.name using the downward API |
QSCS_DEPLOYMENT_SECRET_FILE | Absolute path to the mounted secret, such as /run/qscs-bootstrap/deployment-secret |
QSCS_ADVERTISED_PEER | This pod's unique DNS name, reachable by every peer on TCP 4443 |
For a StatefulSet named qscs, a headless Service named qscs-peer and namespace qscs, the peer address can be $(QSCS_REPLICA_NAME).qscs-peer.qscs.svc.cluster.local. Declare QSCS_REPLICA_NAME before this variable so Kubernetes can expand it, and adjust the names and cluster DNS suffix to your environment.
The initializer name determines which node creates the substrate. It does not require application traffic to enter through that node. Each node generates its own key and receives signed membership and mutual TLS credentials from the enrollment service.
| Variable | Required? | Meaning |
|---|---|---|
ORIGIN | Yes, for initial application setup | Upstream HTTP or HTTPS URL, such as https://origin.example.com |
FRONTEND | Yes when setting ORIGIN | Hostname visitors use, such as app.example.com, without a URL scheme |
UPSTREAM | Optional | Upstream HTTP Host header; defaults to the authority in ORIGIN |
QSCS_INITIAL_CONFIG | Optional | Absolute path to a read-only initial QSCS configuration file |
ORIGIN may include a port, but must not contain credentials, a path prefix, query or fragment. Incoming request paths and queries are forwarded to the upstream. Changing UPSTREAM changes the HTTP Host header; HTTPS certificate verification and SNI still use the hostname from ORIGIN.
Private upstream addresses are disabled by default. To use an internal backend, set AllowPrivateBackends = true in the initial configuration before first boot. localhost refers to the pod's network namespace.
Only the initializer provisions the origin from these variables. Joining nodes receive the substrate's signed configuration. Before claiming, changing the origin variables on the initializer updates its existing route; clearing them does not delete that route. After claiming, manage origins through the control panel.
| Port | Use |
|---|---|
| TCP 8080 | Application HTTP, reached through your ingress or a local port-forward |
| TCP 4443 | Authenticated peer replication between QSCS nodes |
Connect your ingress to the application Service, route the configured FRONTEND hostname and preserve its Host header. Terminate public HTTPS at the ingress. The container does not need to listen on 443 for this arrangement.
Allow DNS, outbound enrollment and monitoring access, upstream access, and peer connectivity in both directions. The peer address must identify one node, not a load-balanced Service. Cross-cluster deployments need their own connectivity; Kubernetes service DNS names are normally local to their cluster.
Start one replica to create the substrate, or start two together. A joining replica that starts first waits for the initializer rather than creating another deployment. To add the second node later, increase the replica count to two while the deployment is still unclaimed.
Check the application through your frontend and inspect node status. Replace the namespace and pod name below with your own:
kubectl --namespace YOUR_NAMESPACE exec YOUR_POD -- qscs status
Both nodes should report the same account handle and substrate ID, with different UUIDs. Allow normal membership refresh to discover the new peer, and check replication separately from listener readiness. Saved state may still be synchronizing after a node starts accepting connections.
Configuring an origin does not establish domain ownership. Spook-managed DNS and certificates require registration and domain verification. QSCS replicates eligible response state, not your application's database; headless serving depends on available saved state and the configured policies.
Claiming links the existing substrate and all its member nodes to a registered account.
qscs status. On the unclaimed administrator, confirm Registration: unclaimed and Can approve claims: yes.sudo if present; retain the exact claim ID and target account ID.The final confirmation transfers ownership. Account handle, substrate ID, node identities, configuration and retained telemetry are preserved. The deployment becomes manageable through the control panel and its retained monitoring data becomes available in SpookVis. A handle or UUID alone is not proof of ownership.
Claiming closes admission through the old shared deployment secret and invalidates unused invitations issued before the claim. Existing nodes continue using their own credentials. Keep their volumes and existing bootstrap inputs for normal restarts; use fresh invitations to add new identities after claiming.
The registered account's allowance applies across all its substrates and account handles. Claiming does not create another free allocation or automatically purchase a paid plan. If the destination account lacks room for the deployment, upgrade before claiming.
Use Billing to upgrade and confirm available capacity in Infrastructure before adding nodes. An entitlement upgrade does not require a new image or substrate.
A node's license remains allocated when its pod is stopped or its volume is deleted. Restoring its original volume preserves its UUID and existing slot. To retire a node, stop it and revoke its license in the control panel. Revocation invalidates its credentials; restoring the old volume does not reverse it. Kubernetes infrastructure charges are separate from QSCS licensing.
After claiming, use an administrator-issued invitation for each additional node. This also works for the second node of a claimed free deployment if the account has an available slot.
qscs enrollment invite.| Variable | Joining node |
|---|---|
QSCS_BOOTSTRAP_MODE | join |
QSCS_INVITE_SOURCE | Absolute path to the mounted invitation JSON |
QSCS_ADVERTISED_PEER | This node's individually reachable peer hostname |
Omit the shared deployment secret, initializer settings and environment-based origin provisioning from this new member. Its invitation identifies the substrate securely, and the authority supplies its configuration. No substrate-name variable or separate claim is required. Joining does not automatically grant administrator or fallback roles.
Each ordinary invitation lasts ten minutes and admits one node. Complete a join before issuing the next ordinary invitation, because generating a new one revokes previous unused invitations for that substrate. If it expires, replace the mounted invitation and restart only the joining container, preserving its volume.
Use a separate workload definition for each invitation-based member so its invitation and volume are not shared with other new nodes. If multiple StatefulSets share an application Service, give them distinct controller selectors and include only members of this substrate in that Service.
Increasing the replica count of the original auto-cluster workload does not enroll fresh nodes after claiming. Rotating the deployment secret cannot reopen anonymous admission for a registered owner. Existing enrolled replicas can still restart normally.
The image supplies the default enrollment and monitoring addresses. Unclaimed operational telemetry is retained for 30 days and includes node identity, version, health and operational counters. The anonymous operational report excludes request bodies, credentials, visitor addresses and request URLs.
Monitoring retries in the background when unreachable and does not block application serving. Enrollment and master-lease renewal have separate security requirements.
With imagePullPolicy: Always, Kubernetes resolves latest when a container starts; changing the tag does not restart running pods. Use your normal rolling-update process, preserve volumes, allow graceful shutdown and record the image digest for reproducible rollback. Kubernetes image behavior
Before deleting workloads, check PVC and storage retention policies. Scaling down can leave both licensed identities and billable volumes in place. Delete storage only when you intend to discard the identity and saved state.
| Symptom | What to check |
|---|---|
| Waiting for the initializer | Matching secret, correct initializer pod name and access to the enrollment service |
deployment_already_exists | Restore the original initializer volume; the secret already belongs to an existing deployment |
deployment_unavailable | The shared grant was claimed, revoked or invalidated; use a fresh invitation for post-claim additions |
node_limit | Available account capacity, including stopped but non-revoked nodes |
administrator_required | Run the approval or invitation command on an administrator of the correct substrate; root privileges do not grant that role |
invitation_unavailable | Expired, consumed, replaced or pre-claim invitation; issue a fresh one and update the joining node's Secret |
Permission denied under /var/lib/qscs | Volume mount, UID/GID 10001 and storage-driver support for group ownership |
| HTTP 421 | The request Host does not match the configured frontend |
Content type
Image
Digest
sha256:133c3795a…
Size
24.8 MB
Last updated
about 5 hours ago
docker pull spooksystems/qscs