The SecurSpaces database
Citrix SecurSpaces™ stores its platform configuration and state in a MongoDB database. This database is the system of record for your deployment. If it is lost or corrupted, the platform cannot operate, even when every other component is healthy.
This section is for platform administrators who deploy and operate SecurSpaces. It assumes you are familiar with Kubernetes, Helm, and your MongoDB hosting model.
| Task | Page |
|---|---|
| Estimate how large the database will be | Database sizing |
| Back it up, on a schedule and before changes | Back up the database |
| Recover from a backup | Restore the database |
What the database stores
The SecurSpaces database (default name strong-network) holds the metadata and state that
define your platform. It does not store the contents of developer workspaces.
Workspace file systems, Docker volumes, and source code live on Kubernetes
Persistent Volume Claims (PVCs) and in your version control system, not in MongoDB.
The database stores, among other things:
-
Organizations, projects, and settings — organization, project, platform, and region configuration, section ordering, and setup checklists.
-
People and access — users, groups, roles, permissions, and identity-provider mappings.
-
Workspace definitions and state — workspace specifications, lifecycle status, schedules, SSH sessions, and the metadata that links a workspace to its project, owner, and persistent volumes.
-
Data mounts — data buckets and workspace mount-point definitions.
-
Integrations — connections to source control and other external services, plus their OAuth and access tokens.
-
Credentials and secrets — API keys and stored credentials. By default these are encrypted and stored in the database. If you configure HashiCorp Vault, secrets are stored in Vault instead of the database (see the next section).
-
Audit and event data — audit-trail and event-log records, plus usage, reporting, and compliance aggregates used by Insights and SIEM integration.
Note The exact collection layout is an internal implementation detail and can change between releases. Treat the database as an opaque unit for backup and restore — always back up and restore the whole database, not individual collections.
Where secrets live: database vs. HashiCorp Vault
By default, SecurSpaces encrypts secrets and credentials and stores them in the database, using an internal encryption key supplied at install time.
If you configure HashiCorp Vault (platform.hashicorpVault in the Helm values), SecurSpaces
stores secrets in Vault instead of the database.
This distinction matters for backups: when you use Vault, a database backup alone does not capture your secrets — you must also back up Vault. When you do not use Vault, the database backup contains the (encrypted) secrets, and you must protect both the backup and the encryption key.
Why the database is critical
The database is the single source of truth for platform configuration and state. SecurSpaces services are stateless by design and read their configuration from MongoDB on startup and during operation. As a result:
- No database, no platform. If MongoDB is unavailable, SecurSpaces services cannot start or serve requests, even when Kubernetes, networking, and storage are healthy.
- Configuration loss is unrecoverable without a backup. Organizations, projects, users, integrations, and workspace metadata exist only in the database. Losing it means rebuilding your platform configuration from scratch.
- Workspace access depends on it. Even though workspace file systems live on PVCs, the metadata that maps a developer to their workspace and its volumes lives in the database. Without that metadata, existing workspaces cannot be reattached.
For these reasons, treat the database as a tier-1, business-critical asset: run it with redundancy, back it up on a schedule, and test your restore procedure.
How the database is deployed
SecurSpaces supports three MongoDB hosting models. Your backup strategy depends on which one you use.
| Hosting model | When it is used | Who operates MongoDB |
|---|---|---|
| Internal MongoDB (Percona) | Deployed by SecurSpaces into your cluster using the Percona Operator. Used for proof of concept and evaluation, and in production where a managed service is not available. | You |
| External / hosted MongoDB | Recommended for production. SecurSpaces connects to an externally managed deployment such as MongoDB Atlas. | The managed service provider |
| Bitnami MongoDB (legacy) | Older internal deployments before the move to Percona. Being phased out. | You |
The bundled internal database is Percona Server for MongoDB 7.0, deployed and
managed by the Percona Operator for MongoDB as a PerconaServerMongoDB custom
resource.
By default the internal deployment uses:
- A single-member replica set (
rs0, size1). For production, increase the replica-set size to at least 3 for high availability. - A 10 GiB persistent volume for data.
- Resource requests of 500m CPU / 1 GiB memory and limits of 2000m CPU / 4 GiB memory.
Note:
A managed MongoDB service is the simplest route to production, because the provider handles redundancy, backups, and scaling for you.
The internal database is fully supported in production, and is the right choice for air-gapped deployments and environments where a managed service is not available. The difference is one of ownership rather than capability: you configure and operate its resilience. The defaults are set for a quick start — a single-member replica set, with backups available but not switched on — so plan for the following before you rely on it:
- A replica set with more than one member, so that the loss of a pod or node does not take the platform down. See Operating principles.
- Backups configured, scheduled, and restore-tested. See Back up the database.
- Resources sized for your own load rather than the defaults. See Sizing.
Operating principles
- Run MongoDB with redundancy in production — a managed service, or a Percona replica set with more than one member that you operate — never a single member.
- Enable continuous / point-in-time backups, not only periodic snapshots.
- Store backups off-cluster and in a separate failure domain.
- Encrypt backups at rest and in transit, and restrict access to backup storage.
- Back up HashiCorp Vault alongside the database when Vault stores your secrets.
- Always back up before upgrades, migrations, and major configuration changes.
- Monitor database size. In-database audit data auto-expires after 360 days; forward events to your SIEM if you need retention beyond that window.
- Test restores on a schedule and document the runbook.