diff --git a/docs/docs.json b/docs/docs.json index cf77aff2f71..ccb776b0542 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -317,6 +317,8 @@ "group": "Self-host Infisical", "pages": [ "self-hosting/overview", + "self-hosting/guides/postgresql", + "self-hosting/guides/redis", { "group": "Installation methods", "pages": [ diff --git a/docs/self-hosting/configuration/requirements.mdx b/docs/self-hosting/configuration/requirements.mdx index 45681b4d90e..4b31646562f 100644 --- a/docs/self-hosting/configuration/requirements.mdx +++ b/docs/self-hosting/configuration/requirements.mdx @@ -55,14 +55,14 @@ Recommended resource allocation based on deployment size. You may require more r Redis is utilized for session management and background tasks in Infisical. - -**Active-passive** setup is recommended for Redis. **Active-active** setup for Redis has not been tested. - + +Redis **active-active geo-replication** is not supported. For multi-region deployments, refer to the [replication guide](/self-hosting/guides/replication) which uses independent Redis instances per region. + Redis requirements: - Use Redis versions 6.x or 7.x. We advise upgrading to at least Redis 6.2. -- Redis Cluster mode is currently not supported; use Redis Standalone, with or without High Availability (HA). +- Supported modes: Standalone, Sentinel (HA), and Cluster. - Redis storage needs are minimal: a setup with 2 vCPU, 4 GB RAM, and 30GB SSD will be sufficient for small deployments. - Set cache eviction policy to `noeviction`. diff --git a/docs/self-hosting/guides/postgresql.mdx b/docs/self-hosting/guides/postgresql.mdx new file mode 100644 index 00000000000..fa81a439f4e --- /dev/null +++ b/docs/self-hosting/guides/postgresql.mdx @@ -0,0 +1,113 @@ +--- +title: "PostgreSQL" +description: "Understand the role PostgreSQL plays in Infisical, what data it stores, and how to operate it safely." +--- + +PostgreSQL is the **authoritative datastore** for all persistent data in Infisical. Every piece of long-lived state — secrets, users, configurations, audit history — is stored in PostgreSQL. It is the single source of truth for the entire platform. + +## What it stores + +| Data | Description | +|------|-------------| +| Secrets | All secrets and their full version history | +| Identities & Users | User accounts, machine identities, and their credentials | +| Projects & Organizations | Project configurations, organization settings, and memberships | +| Access Control | Roles, permissions, and access policies | +| Audit Logs | Records of all actions taken within the platform | +| Integrations | Configuration for third-party integrations and sync targets | +| Certificates & PKI | Certificate authorities, certificates, and PKI configurations | +| Encryption Keys | Encrypted project keys used for secret encryption | + +## Supported modes + +| Mode | Supported | +|------|-----------| +| Standalone (Single Instance) | Yes | +| Read Replicas (Streaming Replication) | Yes | + +For multi-region deployments with read replicas, see the [replication guide](/self-hosting/guides/replication). + +## Configuration + +Configure PostgreSQL connectivity by setting the following environment variables on your Infisical instance. + + + The database user must be granted all privileges on the Infisical database, including the ability to create schemas, tables, indexes, and perform all CRUD operations. + + + + + + Postgres database connection string. + + + + Configure the SSL certificate for securing a Postgres connection by first encoding it in base64. + Use the following command to encode your certificate: `echo "" | base64` + + Many cloud providers provide a CA certificate for their data regions that you can use to secure your connection with SSL. + + + + If you're hosting your database on AWS RDS, you can use their publicly available CA certificate as the database root certificate. + + You can find all the available CA certificates for AWS RDS on the official [AWS RDS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html). + + As an example, if your RDS cluster is hosted in `us-east-1` _(US East, N. Virginia)_, you can use the following root certificate: https://truststore.pki.rds.amazonaws.com/us-east-1/us-east-1-bundle.pem. + + Remember to base64 encode the certificate before setting it as the `DB_ROOT_CERT` environment variable. `cat /path/to/certificate.pem | base64`. + + ```bash + DB_ROOT_CERT=LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1 # .... (base64 encoded certificate) + DB_CONNECTION_URI=?sslmode=verify-ca # or verify-full depending on your security policies + ``` + + + + + + + Postgres database read replica connection strings. It accepts a JSON string. + ``` + DB_READ_REPLICAS=[{"DB_CONNECTION_URI":""}] + ``` + + + Postgres read replica connection string. + + + Configure the SSL certificate for securing a Postgres replica connection by first encoding it in base64. + Use the following command to encode your certificate: `echo "" | base64` + + If not provided, it will use the primary SSL certificate. + + + + + + +## Impact of data loss + +PostgreSQL data loss is **critical and unrecoverable without a backup**. Because PostgreSQL is the sole source of truth for all persistent state, losing this data means losing: + +- All secrets and their version history +- User accounts, identities, and credentials +- Project and organization configurations +- Audit logs and compliance records +- Integration settings and encryption keys + +There is no way to reconstruct this data from other components. Redis caches are ephemeral and do not contain the full dataset. + + + Always maintain regular PostgreSQL backups and test your restore process. Without a working backup, PostgreSQL data loss is **permanent**. + + +## Recommendations + +- **Use a managed service** (e.g., AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL) for automated backups, failover, and maintenance. +- **Enable point-in-time recovery (PITR)** for granular restore capabilities. +- **Test restores regularly**. A backup that has never been tested is not a backup. +- **High availability**: Configure streaming replication with automatic failover to minimize downtime. +- **Version**: Infisical supports PostgreSQL versions 14+, with version 16 being the most extensively tested. + +For hardware sizing, see [hardware requirements](/self-hosting/configuration/requirements). diff --git a/docs/self-hosting/guides/redis.mdx b/docs/self-hosting/guides/redis.mdx new file mode 100644 index 00000000000..04a61175bbf --- /dev/null +++ b/docs/self-hosting/guides/redis.mdx @@ -0,0 +1,141 @@ +--- +title: "Redis" +description: "Understand the role Redis plays in Infisical, why persistence is required, and how to operate it safely." +--- + +Redis serves as both a **caching layer** and a **persistent job queue** in Infisical. Unlike typical cache-only use cases, Infisical relies on Redis to durably store background job data, making persistence a hard requirement. + + + Redis **must be configured with persistence enabled** (AOF, RDB, or both). Infisical uses Redis-backed queues for background processing. A non-persistent Redis instance that restarts will lose all pending and in-progress jobs. + + +## What it stores + +| Data | Description | +|------|-------------| +| Cache | Frequently accessed data and configurations, reducing load on PostgreSQL | +| Background Job Queues | Jobs for secret syncs to third-party integrations, secret rotations, scheduled tasks, webhook deliveries, and audit log processing | +| Job State | Metadata for in-progress, completed, and failed jobs including retry information | +| Session Data | Active user session tokens and ephemeral authentication state | + +## Supported modes + +| Mode | Supported | +|------|-----------| +| Standalone (Single Node) | Yes | +| Sentinel (High Availability) | Yes | +| Cluster | Yes | +| Active-Active Geo-Replication | No | + + + Redis **active-active geo-replication** is not supported. If you need multi-region deployments, refer to Infisical's [replication architecture](/self-hosting/guides/replication) which uses independent Redis instances per region instead. + + +## Configuration + +Configure Redis connectivity by setting the following environment variables on your Infisical instance. + + + + + Redis connection string. For SSL/TLS connections, use the `rediss://` protocol (note the double 's'). + + Examples: + - Without SSL: `redis://localhost:6379` + - With SSL: `rediss://localhost:6379` + - With authentication: `redis://:password@localhost:6379` + - With SSL and authentication: `rediss://:password@localhost:6379` + + + + + Comma-separated list of Sentinel host:port pairs. ``` + 192.168.65.254:26379,192.168.65.254:26380 ``` + + + The name of the Redis master set monitored by Sentinel + + + Whether to use TLS/SSL for Redis Sentinel connection + + + Authentication username for Redis Sentinel + + + Authentication password for Redis Sentinel + + + Authentication username for Redis Node + + + Authentication password for Redis Node + + + + + Comma-separated list of Redis Cluster host:port pairs. ``` + 192.168.65.254:26379,192.168.65.254:26380 ``` + + + Enable Redis TLS encryption on connection. + + + Enable this if you are using AWS encrypt on transit for Elasticache cluster. For more information refer [here](https://github.com/redis/ioredis?tab=readme-ov-file#special-note-aws-elasticache-clusters-with-tls). + + + Authentication username for Redis Node + + + Authentication password for Redis Node + + + + + Comma-separated list of Redis read replicas host:port pairs. ``` + 192.168.65.254:26379,192.168.65.254:26380 ``` + + + The parameters like username, password, TLS, and Redis type of the primary instance will be inherited. + + + +### SSL/TLS + +To connect to Redis with SSL/TLS, use the `rediss://` protocol (note the double 's') in your connection string. + +If your Redis server uses a certificate signed by a private CA or a self-signed certificate, set the `NODE_EXTRA_CA_CERTS` environment variable to the path of your CA certificate file: + +```bash +REDIS_URL=rediss://your-redis-host:6379 +NODE_EXTRA_CA_CERTS=/path/to/ca.crt +``` + +For Redis Sentinel or Cluster mode, use the `REDIS_SENTINEL_ENABLE_TLS` or `REDIS_CLUSTER_ENABLE_TLS` environment variables respectively. + +## Impact of data loss + +Redis data loss is **disruptive but recoverable**. Unlike PostgreSQL, Redis does not hold the source of truth — secrets and configurations remain safe in PostgreSQL. However, the impact depends on what was in Redis at the time: + +- **Cache loss**: No lasting impact. The cache repopulates automatically as read requests come in. You may see a temporary spike in PostgreSQL load until the cache warms up. +- **Queue loss**: Pending background jobs are lost. In-flight operations such as secret syncs to third-party integrations, pending secret rotations, or scheduled webhook deliveries will not complete. These operations will need to be re-triggered manually or will recover on the next scheduled cycle. + +## Why persistence is required + +Infisical uses Redis to manage background job queues. These queues handle operations that must eventually complete: + +- Syncing secrets to external providers (AWS Secrets Manager, GCP Secret Manager, etc.) +- Rotating credentials on a schedule +- Delivering webhooks +- Processing audit logs + +If Redis is running without persistence and restarts, all queued and in-progress jobs disappear silently. There is no mechanism to replay these jobs from PostgreSQL. This can result in secrets being out of sync with third-party integrations, missed rotations, or lost webhook deliveries — with no indication that anything went wrong. + +## Recommendations + +- **Enable persistence** using AOF (`appendonly yes`) with `appendfsync everysec` for a good balance between durability and performance. RDB snapshots can be used as an additional safety net. +- **Set eviction policy to `noeviction`** to prevent Redis from silently dropping queue data under memory pressure. +- **Use Redis 6.2+**. Infisical supports Redis versions 6.x and 7.x, with 6.2 as the minimum recommended version. +- **High availability**: Use Redis Sentinel or a managed Redis service with automatic failover. +- **Monitor memory usage**. Because `noeviction` is required, Redis will reject new writes if it runs out of memory rather than evicting data. Ensure sufficient memory is provisioned for your workload. + +For hardware sizing, see [hardware requirements](/self-hosting/configuration/requirements). diff --git a/docs/self-hosting/overview.mdx b/docs/self-hosting/overview.mdx index de841e63d4b..7cd9d3dbf32 100644 --- a/docs/self-hosting/overview.mdx +++ b/docs/self-hosting/overview.mdx @@ -7,10 +7,23 @@ description: "Learn how to self-host Infisical on your own infrastructure." Self-hosting Infisical lets you retain data on your own infrastructure and network. Many organizations choose self-hosting for benefits in compliance and flexibility. - Compliance: Deploying Infisical in your own environment helps meet strict regulatory requirements (e.g. SOC 2, HIPAA, FIPS 140-3) by aligning with your existing security controls. All data remains under your governance, and Infisical’s architecture supports compliance needs through strong encryption and access controls. -- Flexibility: You have complete control over deployment topology and integrations. Infisical can run in diverse environments. From air-gapped bare-metal servers to Kubernetes clusters or cloud VMs, this flexibility lets you tailor networking, security, and performance configurations to fit your organization’s needs. +- Flexibility: You have complete control over deployment topology and integrations. Infisical can run in diverse environments, from air-gapped bare-metal servers to Kubernetes clusters or cloud VMs, letting you tailor networking, security, and performance configurations to fit your organization’s needs. +## Architecture Overview + +Infisical requires two core infrastructure components alongside the stateless application servers: + +- **[PostgreSQL](/self-hosting/guides/postgresql)** — The sole source of truth for all persistent data including secrets, users, projects, audit logs, and configurations. +- **[Redis](/self-hosting/guides/redis)** — Caching layer and persistent job queue for background processing, session management, and async tasks. + +The application servers are stateless and scale horizontally. See the dedicated [PostgreSQL](/self-hosting/guides/postgresql) and [Redis](/self-hosting/guides/redis) pages for supported modes, data loss implications, and operational recommendations. + +For hardware sizing, see [hardware requirements](/self-hosting/configuration/requirements). For multi-region deployments, see the [replication guide](/self-hosting/guides/replication). + +## Deployment Options + Choose from a number of deployment options listed below to get started.