# How to Configure the Encryption Key for Chat2DB Community: Complete Setup Guide

> Learn how to configure the encryption key for Chat2DB Community. Secure your data by setting a Base64-encoded AES-256 key using JVM properties, environment variables, or a file path. Follow our guide for a complete setup.

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: how-to-guide
- Published: 2026-07-28

---

**To configure the encryption key for Chat2DB Community, you must provide a Base64-encoded AES-256 key via JVM properties, environment variables, or a file path, following a strict priority resolution order that validates the key decodes to exactly 32 bytes.**

Chat2DB Community by OtterMind protects sensitive data such as datasource passwords and AI assistant API keys using **AES-256-GCM** encryption. Before starting the application, you must establish a valid encryption key that persists across restarts. The key resolution logic resides in [`CommunityEncryptionKeyStore.java`](https://github.com/OtterMind/Chat2DB/blob/main/CommunityEncryptionKeyStore.java) and [`AesGcmUtil.java`](https://github.com/OtterMind/Chat2DB/blob/main/AesGcmUtil.java) within the `chat2db-community-tools` module.

## Understanding the Encryption Key Resolution Order

The `CommunityEncryptionKeyStore` class implements a cascading priority system to locate your encryption key. The application evaluates sources sequentially and uses the first valid, non-empty value encountered.

### Resolution Priority

The resolver checks sources in this exact order:

1. **JVM Property**: `chat2db.community.encryption-key` (Base64 string)
2. **Environment Variable**: `CHAT2DB_COMMUNITY_ENCRYPTION_KEY` (Base64 string)
3. **JVM Property**: `chat2db.community.encryption-key-file` (file path)
4. **Environment Variable**: `CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE` (file path)
5. **Default File**: `~/.config/chat2db-community/encryption.key`

If none of these sources provide a valid key, the application aborts during startup in Web and headless modes. Desktop mode can automatically generate a missing key file.

### Validation Requirements

The `AesGcmUtil` utility validates that decoded keys measure exactly **32 bytes** (256 bits), which is the required size for AES-256-GCM encryption. Keys failing this validation trigger startup errors with specific messages defined in the utility class.

## Generating a New Encryption Key

Use the provided initialization script to create a cryptographically secure key. The script generates a 44-character Base64 string (including padding) and writes it to your chosen location.

Run the script from the repository root:

```bash
./script/security/init-community-encryption-key.sh

```

By default, this creates `~/.config/chat2db-community/encryption.key`. To specify a custom path:

```bash
./script/security/init-community-encryption-key.sh /secure/path/chat2db-community.key

```

The script refuses to overwrite existing valid keys and enforces regular-file permissions to prevent directory traversal attacks.

## Configuration Methods

You can supply the encryption key through multiple mechanisms depending on your deployment environment.

### Method 1: JVM System Property (Direct Key)

Pass the Base64 key directly as a system property when launching the JVM:

```bash
java -Dchat2db.community.encryption-key=<BASE64_KEY> \
    -Dchat2db.runtime.mode=community \
    -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

```

Replace `<BASE64_KEY>` with the full 44-character string generated by the initialization script.

### Method 2: Environment Variable

Set the key in your shell environment before starting the application:

```bash
export CHAT2DB_COMMUNITY_ENCRYPTION_KEY=<BASE64_KEY>
java -Dchat2db.runtime.mode=community \
    -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

```

### Method 3: Key File via JVM Property

Point to an existing key file using a system property:

```bash
java -Dchat2db.community.encryption-key-file=/secure/path/chat2db-community.key \
    -Dchat2db.runtime.mode=community \
    -Dchat2db.mode=WEB \
    -Dchat2db.gui=false \
    -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

```

### Method 4: Key File via Environment Variable

Use an environment variable to specify the key file path:

```bash
export CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE=/secure/path/chat2db-community.key
java -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

```

### Method 5: Default File Location

Place your key at `~/.config/chat2db-community/encryption.key` and start the application without additional configuration. The resolver automatically discovers this file as the final fallback.

## Practical Configuration Examples

These examples demonstrate real-world deployment scenarios for Chat2DB Community.

### Docker Deployment

Mount your encryption key as a read-only secret:

```bash
./script/security/init-community-encryption-key.sh

docker run -d \
  --name chat2db-community \
  --restart unless-stopped \
  -p 127.0.0.1:10825:10825 \
  -v "$HOME/.chat2db-community-docker:/root/.chat2db-community" \
  -e CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE=/run/secrets/chat2db-community-encryption.key \
  -v "$HOME/.config/chat2db-community/encryption.key:/run/secrets/chat2db-community-encryption.key:ro" \
  chat2db/chat2db:latest

```

This approach keeps the key outside the container image and uses the environment variable resolution path.

### Web Mode Startup

For headless server deployments with a custom key location:

```bash
java -Dloader.path=chat2db-community-server/chat2db-community-start/target/lib \
    -Dchat2db.runtime.mode=community \
    -Dchat2db.mode=WEB \
    -Dchat2db.gui=false \
    -Dchat2db.network.status=OFFLINE \
    -Dchat2db.community.encryption-key-file=/secure/path/chat2db-community.key \
    -Dserver.address=127.0.0.1 \
    -Dserver.port=10825 \
    -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

```

### Desktop Mode Considerations

Desktop mode behaves differently from Web mode. While Web and headless modes require a pre-existing valid key and abort if none is found, Desktop mode can automatically create the default key file at `~/.config/chat2db-community/encryption.key` during first startup. However, explicitly configuring the key using the methods above ensures consistency across all runtime modes.

## Source Code References

The encryption key implementation spans three critical files in the OtterMind/Chat2DB repository:

- **[`CommunityEncryptionKeyStore.java`](https://github.com/OtterMind/Chat2DB/blob/main/CommunityEncryptionKeyStore.java)**: Implements the resolution priority logic and key validation located at [`chat2db-community-server/chat2db-community-tools/src/main/java/ai/chat2db/community/tools/security/CommunityEncryptionKeyStore.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-tools/src/main/java/ai/chat2db/community/tools/security/CommunityEncryptionKeyStore.java)
- **[`AesGcmUtil.java`](https://github.com/OtterMind/Chat2DB/blob/main/AesGcmUtil.java)**: Contains AES-256-GCM constants, property name strings, and validation algorithms located at [`chat2db-community-server/chat2db-community-tools/src/main/java/ai/chat2db/community/tools/security/AesGcmUtil.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-tools/src/main/java/ai/chat2db/community/tools/security/AesGcmUtil.java)
- **[`init-community-encryption-key.sh`](https://github.com/OtterMind/Chat2DB/blob/main/init-community-encryption-key.sh)**: Bash script for secure key generation located at [`script/security/init-community-encryption-key.sh`](https://github.com/OtterMind/Chat2DB/blob/main/script/security/init-community-encryption-key.sh)

## Summary

- **AES-256-GCM** encryption protects all stored credentials in Chat2DB Community.
- The resolver checks **five sources** in strict priority: JVM property, environment variable, file property, file environment variable, and default file path.
- Keys must decode to exactly **32 bytes**; the initialization script generates compliant 44-character Base64 strings.
- Web and headless modes **require** a valid key before startup, while Desktop mode can auto-generate missing keys.
- Use the initialization script at [`script/security/init-community-encryption-key.sh`](https://github.com/OtterMind/Chat2DB/blob/main/script/security/init-community-encryption-key.sh) to create keys securely without manual encoding.

## Frequently Asked Questions

### What happens if I lose my Chat2DB Community encryption key?

If you lose the encryption key, all encrypted datasource passwords and AI API keys stored in the database become permanently unreadable. You must regenerate the key and re-enter all credentials through the UI. This data loss occurs because AES-256-GCM encryption is symmetric and irreversible without the original key.

### How do I generate a new encryption key for Chat2DB Community?

Execute the [`init-community-encryption-key.sh`](https://github.com/OtterMind/Chat2DB/blob/main/init-community-encryption-key.sh) script from the repository root. This script generates a cryptographically secure 256-bit key, encodes it as Base64, and writes it to the default location or a custom path you specify. The script prevents accidental overwrites of existing valid keys.

### Can I use the same encryption key across multiple Chat2DB Community installations?

Yes, you can reuse the same Base64 key across multiple instances, which allows shared credential databases or consistent environments. However, ensure all installations use the exact same key string or file contents, as any variation will cause decryption failures for existing encrypted data.

### Why does Chat2DB Community require a 32-byte encryption key?

The application implements **AES-256-GCM**, which requires a 256-bit (32-byte) key for its encryption operations. The validation logic in [`AesGcmUtil.java`](https://github.com/OtterMind/Chat2DB/blob/main/AesGcmUtil.java) enforces this length to maintain cryptographic security standards. Keys shorter or longer than 32 bytes cause immediate startup failures with validation error messages.