Make authentication database path configurable via DATABASE_PATH environment variable

[werdnum]

Summary

The authentication database path is now configurable via the DATABASE_PATH environment variable, enabling persistent data storage across container restarts and flexible deployment scenarios.

Problem

Previously, the authentication database path was hardcoded to server/database/auth.db. This created issues for containerized deployments where:

• Database data was lost on container restarts
• Volume mounts couldn't be used for persistence
• No flexibility for custom storage locations

Solution

Added support for the DATABASE_PATH environment variable with the following features:

✅ Configurable Path

The database location can now be set via environment variable:

DATABASE_PATH=/data/auth.db npm start

✅ Automatic Directory Creation

If a custom path is provided, the database directory is automatically created:

// Automatically creates /data directory if it doesn't exist
DATABASE_PATH=/data/auth.db

✅ Backward Compatible

No changes required for existing deployments - defaults to server/database/auth.db when DATABASE_PATH is not set.

✅ Enhanced Logging

The actual database path is now logged on startup for easier debugging:

Connected to SQLite database at: /data/auth.db

Usage

Docker Deployment

docker run -d \
  -e DATABASE_PATH=/data/auth.db \
  -v claude-data:/data \
  -p 3001:3001 \
  your-image

Docker Compose

services:
  claude-code-ui:
    environment:
      - DATABASE_PATH=/data/auth.db
    volumes:
      - claude-data:/data

Local Development

Add to .env file:

DATABASE_PATH=/var/lib/claude-ui/auth.db

Testing

All functionality has been thoroughly tested:

• ✅ Default path behavior (backward compatibility)
• ✅ Custom path configuration
• ✅ Directory auto-creation
• ✅ Authentication flow (user creation, login, password verification)
• ✅ Database persistence

Files Changed

• server/database/db.js - Added environment variable support and directory creation logic
• .env.example - Documented the new DATABASE_PATH variable with examples

Migration Guide

For existing deployments: No changes needed.

For container deployments wanting persistence:

1. Set DATABASE_PATH environment variable
2. Mount a volume at the database directory
3. Restart the container

The database will be created at the new location on first startup.

Original prompt

Make the authentication database (and any other databases that should be persisted across container restarts) path configurable with an environment variable instead of hardcoding to live in the database directory.

Summary by CodeRabbit

• New Features

  • Support configuring a custom database location via the DATABASE_PATH environment variable.
  • Automatically creates the database directory if it doesn’t exist when a custom path is provided.
  • Connection logs now display the actual database path for improved transparency.

• Documentation

  • Updated the environment example with a new database configuration section, including commented guidance for DATABASE_PATH and related notes.

[coderabbitai]

Walkthrough

Adds a commented DATABASE CONFIGURATION block to .env.example. Updates server/database/db.js to read DATABASE_PATH, create the parent directory when a custom path is provided, and log the resolved database path prior to connecting. No exported API changes.

Changes

Cohort / File(s)	Summary of Changes
Environment example docs \.env.example	Added a commented DATABASE CONFIGURATION block with guidance for DATABASE_PATH and related notes; no new variable assignments and existing content unchanged.
Database initialization and logging server/database/db.js	Reads DATABASE_PATH from environment; resolves DB path (falls back to default); when a custom path is set, ensures parent directory exists (recursive mkdir) and logs creation/verification; logs the actual resolved DB path before connecting; no public API or export changes.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    actor App
    participant Env as Environment
    participant DBM as DB Module
    participant FS as File System
    participant Log as Logger
    participant DB as DB Client

    App->>DBM: initialize()
    DBM->>Env: read DATABASE_PATH
    Env-->>DBM: value or undefined

    rect rgba(200,230,255,0.35)
    note right of DBM: Pre-connection setup
    alt DATABASE_PATH is set
        DBM->>FS: ensure parent dir exists (mkdir -p)
        FS-->>DBM: ok
        DBM->>Log: "Created/verified DB dir for custom path"
    else default path
        DBM->>Log: "Using default DB path"
    end
    end

    rect rgba(220,255,220,0.35)
    note right of DBM: Connect
    DBM->>Log: "Connecting to DB at <resolved path>"
    DBM->>DB: connect(resolvedPath)
    DB-->>DBM: ready
    DBM-->>App: db handle
    end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I thump my paws where paths are planned,
I dig a route with tidy hand.
Env signs point the way to go,
I make the hole and watch it grow.
A snug database burrow—soft and grand. 🐇💾

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit's high-level summary is enabled.
Title Check	✅ Passed	The title clearly and concisely summarizes the primary change, which is making the authentication database path configurable via the DATABASE_PATH environment variable as implemented in db.js and documented in .env.example.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cf171a7 and 1bfbab0.

📒 Files selected for processing (1)

• server/database/db.js (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• server/database/db.js

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

server/database/db.js (1)

14-21: Consider using async fs operations for consistency.

The synchronous fs.existsSync and fs.mkdirSync operations block the event loop during startup. While this is acceptable for one-time initialization, using async operations would be more consistent with the existing initializeDatabase function and Node.js best practices.

If you'd like to refactor to async operations, you could create a setup function:

// After imports
const setupDatabase = async () => {
  // Ensure database directory exists if custom path is provided
  if (process.env.DATABASE_PATH) {
    const dbDir = path.dirname(DB_PATH);
    try {
      await fs.promises.mkdir(dbDir, { recursive: true });
      console.log(`Created database directory: ${dbDir}`);
    } catch (error) {
      if (error.code !== 'EEXIST') {
        console.error(`Failed to create database directory ${dbDir}:`, error.message);
        throw error;
      }
    }
  }
};

// Then call it before database operations
await setupDatabase();

Note: This would require refactoring how the module is initialized.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7d0fd14 and cf171a7.

📒 Files selected for processing (2)

• .env.example (1 hunks)
• server/database/db.js (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

server/database/db.js (1)

server/index.js (3)

• path (975-975)
• __dirname (9-9)
• fs (976-976)

🔇 Additional comments (3)

.env.example (1)

16-25: LGTM!

The DATABASE CONFIGURATION documentation is clear, concise, and provides helpful examples for different deployment scenarios (default, Docker). The note about persistent volumes for containers is particularly valuable.

server/database/db.js (2)

10-11: LGTM!

The environment variable reading with fallback to the default path is clean and maintains backward compatibility as stated in the PR objectives.

---

25-25: LGTM!

The enhanced logging that shows the actual database path is a useful improvement for debugging and observability, especially when troubleshooting configuration issues in different environments.