diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index 69fbe44..fb66f90 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -43,6 +43,82 @@ If you prefer manual setup:
    docker-compose up -d
    ```
 
+## Data Persistence
+
+**IMPORTANT: Your data is safely stored outside the Docker container**
+
+### How It Works
+
+The Docker setup uses a **bind mount** to persist data:
+
+```yaml
+volumes:
+  - ./data:/app/data  # Host directory : Container directory
+```
+
+- **Host Location**: `./data/` (on your ZimaOS filesystem)
+- **Container Location**: `/app/data/` (inside the container)
+- **What's Stored**: 
+  - User credentials (hashed)
+  - Budget data (encrypted)
+  - Transaction history
+  - Envelope configurations
+
+### Data Survives
+
+✅ Container restarts  
+✅ Container rebuilds  
+✅ Docker Compose down/up  
+✅ System reboots (with restart: unless-stopped)  
+
+### Data is Lost If
+
+❌ You delete the `./data` directory  
+❌ You run `docker-compose down -v` (removes volumes)
+
+### Testing Persistence
+
+Run the included test script:
+```bash
+./test-persistence.sh
+```
+
+This verifies that:
+1. Data directory is correctly mounted
+2. Files created in container appear on host
+3. Data survives container restarts
+
+### Backup Your Data
+
+**Recommended backup schedule:**
+
+```bash
+# Quick backup
+cp -r data data-backup-$(date +%Y%m%d)
+
+# Compressed backup
+tar -czf capsule-backup-$(date +%Y%m%d).tar.gz data/
+
+# Restore from backup
+tar -xzf capsule-backup-YYYYMMDD.tar.gz
+```
+
+**Using ZimaOS:**
+- Enable automatic snapshots for the Capsule directory
+- Or use ZimaOS built-in backup features
+
+### Data Location on ZimaOS
+
+Depending on where you deploy:
+- **SMB/File Manager**: Check the upload location
+- **SSH Deployment**: Usually `/mnt/your-pool/apps/capsule/data`
+- **Docker Apps**: May be in `/var/lib/docker/volumes/`
+
+To find exact location:
+```bash
+docker inspect capsule-budget | grep -A 10 "Mounts"
+```
+
 ## ZimaOS Integration
 
 ### Using ZimaOS Apps
diff --git a/data/.gitignore b/data/.gitignore
index c85218f..ab3ee8a 100644
--- a/data/.gitignore
+++ b/data/.gitignore
@@ -1,5 +1,6 @@
 # Exclude all user data files
 *.json
 
-# Keep this .gitignore file
+# Keep these files
 !.gitignore
+!README.md
diff --git a/data/README.md b/data/README.md
new file mode 100644
index 0000000..cb9eb27
--- /dev/null
+++ b/data/README.md
@@ -0,0 +1,68 @@
+# Capsule User Data Directory
+
+This directory contains all your encrypted budget data.
+
+## What's Stored Here
+
+- **users.json** - User credentials (SHA-256 hashed passwords)
+- **{userId}.json** - Individual user budget data (AES-GCM encrypted)
+- **locks/** - File locks for concurrent access protection
+
+## Data Persistence
+
+✅ This directory is **mounted as a Docker volume**  
+✅ Data persists across container restarts  
+✅ Data persists across container rebuilds  
+✅ Data survives system reboots  
+
+## Backup
+
+**Recommended:** Back up this entire directory regularly
+
+```bash
+# From parent directory
+tar -czf capsule-backup-$(date +%Y%m%d).tar.gz data/
+```
+
+## Security
+
+- All budget data is encrypted with AES-GCM
+- Passwords are hashed with SHA-256
+- NEVER share your ENCRYPTION_KEY
+- Keep this directory secure
+
+## File Structure
+
+```
+data/
+├── users.json              # User accounts
+├── user-abc123.json        # User 1 data (encrypted)
+├── user-def456.json        # User 2 data (encrypted)
+└── locks/                  # File locks
+    ├── users.json.lock
+    └── ...
+```
+
+## Troubleshooting
+
+**Data not persisting?**
+
+Check Docker volume mount:
+```bash
+docker inspect capsule-budget | grep -A 10 "Mounts"
+```
+
+Should show:
+```json
+"Mounts": [{
+    "Source": "/path/to/capsule/data",
+    "Destination": "/app/data"
+}]
+```
+
+**Permission issues?**
+
+Ensure directory has correct permissions:
+```bash
+chmod 755 data
+```
diff --git a/deploy.sh b/deploy.sh
index 9077392..4a206ca 100755
--- a/deploy.sh
+++ b/deploy.sh
@@ -43,6 +43,19 @@ echo ""
 echo "🚀 Starting Capsule..."
 docker-compose up -d
 
+echo ""
+echo "⏳ Waiting for container to start..."
+sleep 5
+
+# Verify data directory is mounted
+echo ""
+echo "🔍 Verifying data persistence..."
+if docker-compose exec capsule ls -la /app/data >/dev/null 2>&1; then
+    echo "✅ Data directory is correctly mounted in container"
+else
+    echo "⚠️  Warning: Could not verify data directory mount"
+fi
+
 echo ""
 echo "✅ Deployment complete!"
 echo ""
@@ -57,4 +70,8 @@ echo "   docker-compose restart       # Restart container"
 echo "   docker-compose down          # Stop and remove container"
 echo ""
 echo "💾 Your data is stored in: ./data/"
+echo "   - This directory persists across container restarts"
+echo "   - Back it up regularly!"
+echo ""
+echo "🧪 To test data persistence: ./test-persistence.sh"
 echo ""
diff --git a/test-persistence.sh b/test-persistence.sh
new file mode 100755
index 0000000..da4172b
--- /dev/null
+++ b/test-persistence.sh
@@ -0,0 +1,72 @@
+#!/bin/bash
+
+# Test script to verify Docker data persistence
+
+echo "🧪 Testing Capsule Docker Data Persistence..."
+echo ""
+
+# Ensure data directory exists
+mkdir -p data
+
+# Start container
+echo "📦 Starting container..."
+docker-compose up -d
+
+# Wait for container to be ready
+echo "⏳ Waiting for container to start..."
+sleep 10
+
+# Check if container is running
+if ! docker-compose ps | grep -q "Up"; then
+    echo "❌ Container failed to start"
+    docker-compose logs
+    exit 1
+fi
+
+echo "✅ Container is running"
+echo ""
+
+# Create a test file in the data directory
+TEST_FILE="data/persistence-test-$(date +%s).txt"
+echo "test data from host" > "$TEST_FILE"
+echo "📝 Created test file: $TEST_FILE"
+
+# Check if file is visible in container
+echo "🔍 Checking if file is visible in container..."
+if docker-compose exec capsule ls -la /app/data | grep -q "persistence-test"; then
+    echo "✅ Test file is visible in container"
+else
+    echo "❌ Test file NOT visible in container"
+    exit 1
+fi
+
+# Restart container
+echo ""
+echo "🔄 Restarting container to test persistence..."
+docker-compose restart
+
+# Wait for restart
+sleep 10
+
+# Check if file still exists after restart
+echo "🔍 Checking if test file persists after restart..."
+if [ -f "$TEST_FILE" ]; then
+    echo "✅ Test file persisted after container restart"
+else
+    echo "❌ Test file was lost after restart"
+    exit 1
+fi
+
+# Clean up test file
+rm "$TEST_FILE"
+
+echo ""
+echo "✅ All persistence tests passed!"
+echo ""
+echo "Data persistence verified:"
+echo "  - Host directory: ./data"
+echo "  - Container directory: /app/data"
+echo "  - Data survives container restarts: YES"
+echo ""
+echo "Your user data will be safely stored in ./data/"
+echo ""