HUB
Sign inSign up

spooksystems/qscs

By spooksystems

•Updated about 5 hours ago

Image
0

880

spooksystems/qscs repository overview

⁠spooksystems/qscs

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⁠.

⁠Image and requirements

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.

⁠1. Configure the Kubernetes workload

Create a StatefulSet with the following settings using your preferred Kubernetes deployment tool.

SettingConfiguration
Imagedocker.io/spooksystems/qscs:latest
ReplicasStart with 1 or 2
User and grouprunAsUser: 10001, runAsGroup: 10001, fsGroup: 10001
Persistent storageA separate writable volume for each replica, mounted at /var/lib/qscs
Storage capacitySize for your application; 10 GiB per node is an example starting allocation
Peer discoveryA headless Service with publishNotReadyAddresses: true and stable per-pod DNS names
Application accessA Service forwarding to TCP 8080
ReadinessTCP check on port 8080
Shutdown grace period90 seconds
Image pull policyAlways 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⁠

⁠2. Configure automatic enrollment

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:

VariableValue
QSCS_BOOTSTRAP_MODEauto-cluster
QSCS_INITIAL_REPLICAThe exact initializer pod name, such as qscs-0
QSCS_REPLICA_NAMEPopulate from Kubernetes metadata.name using the downward API
QSCS_DEPLOYMENT_SECRET_FILEAbsolute path to the mounted secret, such as /run/qscs-bootstrap/deployment-secret
QSCS_ADVERTISED_PEERThis 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.

⁠3. Configure the application

VariableRequired?Meaning
ORIGINYes, for initial application setupUpstream HTTP or HTTPS URL, such as https://origin.example.com
FRONTENDYes when setting ORIGINHostname visitors use, such as app.example.com, without a URL scheme
UPSTREAMOptionalUpstream HTTP Host header; defaults to the authority in ORIGIN
QSCS_INITIAL_CONFIGOptionalAbsolute 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.

⁠4. Connect the network and start the nodes

PortUse
TCP 8080Application HTTP, reached through your ingress or a local port-forward
TCP 4443Authenticated 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.

⁠Claim the deployment

Claiming links the existing substrate and all its member nodes to a registered account.

  1. Create or sign in to a verified account in the Spook Systems control panel⁠.
  2. Read the account handle with qscs status. On the unclaimed administrator, confirm Registration: unclaimed and Can approve claims: yes.
  3. Select Claim existing deployment, enter the handle and choose Discover. Check the destination username and account ID.
  4. Within ten minutes, run the portal's approval command on that unclaimed administrator. When using a container shell, remove only the leading sudo if present; retain the exact claim ID and target account ID.
  5. Select Check approval, review the discovered nodes, select each node and choose Claim deployment. Refresh the list if membership changed during discovery.

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.

⁠Licensing and expansion

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.

⁠Join an existing substrate

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.

  1. Prepare a new stateful node with its own volume and a stable peer address. Keep the existing nodes' configuration and identities.
  2. On a running administrator of the target substrate, run qscs enrollment invite.
  3. Store the returned JSON privately in a Kubernetes Secret and mount it read-only on the joining node.
  4. Configure the joining container with the settings below and start it.
  5. Check that it has the existing account handle and substrate ID, a new UUID, and the expected ownership. For a claimed substrate, confirm it appears in Infrastructure and SpookVis after reporting updates.
VariableJoining node
QSCS_BOOTSTRAP_MODEjoin
QSCS_INVITE_SOURCEAbsolute path to the mounted invitation JSON
QSCS_ADVERTISED_PEERThis 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.

⁠Monitoring, updates and storage

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.

⁠Troubleshooting

SymptomWhat to check
Waiting for the initializerMatching secret, correct initializer pod name and access to the enrollment service
deployment_already_existsRestore the original initializer volume; the secret already belongs to an existing deployment
deployment_unavailableThe shared grant was claimed, revoked or invalidated; use a fresh invitation for post-claim additions
node_limitAvailable account capacity, including stopped but non-revoked nodes
administrator_requiredRun the approval or invitation command on an administrator of the correct substrate; root privileges do not grant that role
invitation_unavailableExpired, consumed, replaced or pre-claim invitation; issue a fresh one and update the joining node's Secret
Permission denied under /var/lib/qscsVolume mount, UID/GID 10001 and storage-driver support for group ownership
HTTP 421The request Host does not match the configured frontend

Tag summary

Content type

Image

Digest

sha256:133c3795a…

Size

24.8 MB

Last updated

about 5 hours ago

docker pull spooksystems/qscs