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

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 and 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:

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

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

./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:

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:

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:

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:

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:

./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:

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: 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
• 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
• init-community-encryption-key.sh: Bash script for secure key generation located at 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 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 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 enforces this length to maintain cryptographic security standards. Keys shorter or longer than 32 bytes cause immediate startup failures with validation error messages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}