Fix SSH tunnel Docker build for Dokploy deployment

Changes:
- Fix Dockerfile COPY path from ../secrets to secrets/ (Docker doesn't allow parent directory access)
- Create ssh-tunnel/secrets/ directory structure with comprehensive README
- Add .dockerignore for ssh-tunnel to optimize build context
- Add DOKPLOY_DEPLOYMENT.md with complete deployment guide including:
  * SSH key configuration options (repository, secrets manager, BuildKit)
  * Environment variables setup
  * Step-by-step deployment instructions
  * Troubleshooting section
  * Security best practices
- Update .gitignore to allow secrets/README.md files for documentation

This resolves the Dokploy build failure: "failed to calculate checksum of ref... /secrets/roa_oracle_server: not found"

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.gitignore

@@ -407,6 +407,8 @@ scan_*.json
 sdist/
 sdist/
 secrets/
+# Allow documentation in secrets directories
+!**/secrets/README.md
 security_*.json
 share/python-wheels/
 sqlnet.ora

DOKPLOY_DEPLOYMENT.md

@@ -0,0 +1,918 @@
+# ROA2WEB Deployment Guide for Dokploy
+
+This guide provides step-by-step instructions for deploying ROA2WEB to Dokploy, a modern Docker-based deployment platform.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Detailed Setup](#detailed-setup)
+  - [1. SSH Key Configuration](#1-ssh-key-configuration)
+  - [2. Environment Variables](#2-environment-variables)
+  - [3. Repository Setup](#3-repository-setup)
+  - [4. Deployment](#4-deployment)
+- [Post-Deployment](#post-deployment)
+- [Monitoring and Maintenance](#monitoring-and-maintenance)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Prerequisites
+
+Before deploying to Dokploy, ensure you have:
+
+- ✅ A Dokploy instance running (cloud or self-hosted)
+- ✅ Access to your Git repository (GitHub, GitLab, Gitea, etc.)
+- ✅ SSH private key for Oracle database tunnel (`roa_oracle_server`)
+- ✅ Oracle database credentials
+- ✅ JWT secret key for authentication
+- ✅ Telegram bot token (if using Telegram bot feature)
+- ✅ Claude API key (if using Telegram bot with Claude SDK)
+
+---
+
+## Quick Start
+
+### Option 1: Using Pre-Configured Secrets (Recommended)
+
+1. **Add SSH Key to Repository**:
+   ```bash
+   # In your local repository
+   cp /path/to/your/roa_oracle_server ./ssh-tunnel/secrets/
+   chmod 600 ./ssh-tunnel/secrets/roa_oracle_server
+   git add ssh-tunnel/secrets/roa_oracle_server
+   git commit -m "Add SSH key for deployment"
+   git push
+   ```
+
+   ⚠️ **IMPORTANT**: Only do this if your repository is **private**!
+
+2. **Set Environment Variables in Dokploy**:
+   - Navigate to your application in Dokploy
+   - Go to "Environment Variables" section
+   - Add all required variables (see [Environment Variables](#2-environment-variables))
+
+3. **Deploy**:
+   - Click "Deploy" in Dokploy
+   - Wait for build and deployment to complete
+   - Check logs for any errors
+
+### Option 2: Using Dokploy Secrets Manager (Most Secure)
+
+1. **Upload SSH Key via Dokploy UI**:
+   - Go to Dokploy → Secrets → Create New Secret
+   - Name: `SSH_PRIVATE_KEY`
+   - Content: Paste your SSH private key content
+   - Save
+
+2. **Modify `docker-compose.yml`** to use the secret:
+   ```yaml
+   roa-ssh-tunnel:
+     secrets:
+       - ssh_private_key
+     # ... rest of config
+
+   secrets:
+     ssh_private_key:
+       external: true
+   ```
+
+3. **Update Dockerfile** to use mounted secret:
+   ```dockerfile
+   # Copy SSH key from mounted secret
+   RUN --mount=type=secret,id=ssh_private_key \
+       cp /run/secrets/ssh_private_key /home/tunnel/.ssh/roa_oracle_server && \
+       chown tunnel:tunnel /home/tunnel/.ssh/roa_oracle_server && \
+       chmod 600 /home/tunnel/.ssh/roa_oracle_server
+   ```
+
+---
+
+## Detailed Setup
+
+### 1. SSH Key Configuration
+
+The SSH tunnel requires a private key to connect to the Oracle database server. Choose one of the following methods:
+
+#### Method A: Include in Repository (Private Repos Only)
+
+1. **Prepare the SSH Key**:
+   ```bash
+   cd /mnt/e/proiecte/roa2web
+
+   # Copy your SSH key to the secrets directory
+   cp /path/to/your/roa_oracle_server ./ssh-tunnel/secrets/
+
+   # Set proper permissions
+   chmod 600 ./ssh-tunnel/secrets/roa_oracle_server
+
+   # Verify the key
+   ls -l ./ssh-tunnel/secrets/roa_oracle_server
+   ```
+
+2. **Commit to Repository** (ONLY if private!):
+   ```bash
+   git add ssh-tunnel/secrets/roa_oracle_server
+   git commit -m "Add SSH key for production deployment"
+   git push origin main
+   ```
+
+3. **Test Locally**:
+   ```bash
+   # Test SSH connection
+   ssh -i ./ssh-tunnel/secrets/roa_oracle_server \
+       -p 22122 \
+       roa2web@83.103.197.79 \
+       "echo 'Connection successful'"
+
+   # Test Docker build
+   docker build -t test-ssh-tunnel ./ssh-tunnel
+   ```
+
+#### Method B: Use Dokploy Environment Files
+
+1. **In Dokploy UI**:
+   - Navigate to: Application → Settings → Environment Files
+   - Click "Add Environment File"
+   - File path: `/home/tunnel/.ssh/roa_oracle_server`
+   - Content: Paste your SSH private key
+   - Permissions: `600`
+
+2. **Mount in `docker-compose.yml`**:
+   ```yaml
+   roa-ssh-tunnel:
+     volumes:
+       - ${SSH_KEY_FILE}:/home/tunnel/.ssh/roa_oracle_server:ro
+   ```
+
+#### Method C: Use Docker BuildKit Secrets
+
+1. **In Dokploy Build Settings**:
+   - Enable BuildKit
+   - Add build secret: `id=ssh_key,src=<path_to_key>`
+
+2. **Update Dockerfile**:
+   ```dockerfile
+   RUN --mount=type=secret,id=ssh_key \
+       cp /run/secrets/ssh_key /home/tunnel/.ssh/roa_oracle_server && \
+       chmod 600 /home/tunnel/.ssh/roa_oracle_server && \
+       chown tunnel:tunnel /home/tunnel/.ssh/roa_oracle_server
+   ```
+
+---
+
+### 2. Environment Variables
+
+Configure these environment variables in Dokploy:
+
+#### Required Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `ORACLE_USER` | Oracle database username | `CONTAFIN_ORACLE` |
+| `ORACLE_PASSWORD` | Oracle database password | `your_secure_password` |
+| `ORACLE_HOST` | Oracle host (via tunnel) | `roa-ssh-tunnel` (in Docker network) |
+| `ORACLE_PORT` | Oracle port (via tunnel) | `1526` |
+| `ORACLE_SID` | Oracle SID | `ROA` |
+| `JWT_SECRET_KEY` | Secret key for JWT tokens | Generate: `openssl rand -hex 32` |
+| `JWT_ALGORITHM` | JWT algorithm | `HS256` |
+| `JWT_EXPIRE_MINUTES` | Token expiration time | `30` |
+
+#### SSH Tunnel Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `SSH_SERVER` | Remote SSH server | `83.103.197.79` |
+| `SSH_PORT` | SSH port | `22122` |
+| `SSH_USER` | SSH username | `roa2web` |
+| `REMOTE_HOST` | Oracle database host (remote) | `10.0.20.36` |
+| `REMOTE_PORT` | Oracle database port (remote) | `1521` |
+
+#### Telegram Bot Variables (Optional)
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `TELEGRAM_BOT_TOKEN` | Telegram bot token from @BotFather | `123456:ABC-DEF...` |
+| `CLAUDE_API_KEY` | Claude API key for agent features | `sk-ant-...` |
+| `TELEGRAM_LOG_LEVEL` | Logging level | `INFO` |
+
+#### Optional Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ENVIRONMENT` | Environment name | `production` |
+| `DEBUG` | Enable debug mode | `false` |
+| `DOMAIN` | Domain for the application | `roa2web.yourdomain.com` |
+| `SSL_EMAIL` | Email for Let's Encrypt SSL | `admin@yourdomain.com` |
+| `REDIS_PASSWORD` | Redis password | `roa2web_redis_password` |
+
+#### Setting Variables in Dokploy
+
+1. Go to your application in Dokploy
+2. Navigate to **Settings** → **Environment Variables**
+3. Click **Add Environment Variable**
+4. Add each variable one by one:
+   - Key: `ORACLE_PASSWORD`
+   - Value: `your_secure_password`
+   - Click **Save**
+5. Repeat for all required variables
+
+**Alternative: Bulk Import**
+
+Create a `.env` file and import it:
+
+```bash
+# .env.production
+ORACLE_USER=CONTAFIN_ORACLE
+ORACLE_PASSWORD=your_secure_password
+ORACLE_HOST=roa-ssh-tunnel
+ORACLE_PORT=1526
+ORACLE_SID=ROA
+JWT_SECRET_KEY=your_generated_secret_key
+JWT_ALGORITHM=HS256
+JWT_EXPIRE_MINUTES=30
+SSH_SERVER=83.103.197.79
+SSH_PORT=22122
+SSH_USER=roa2web
+REMOTE_HOST=10.0.20.36
+REMOTE_PORT=1521
+TELEGRAM_BOT_TOKEN=your_telegram_token
+CLAUDE_API_KEY=your_claude_key
+ENVIRONMENT=production
+DEBUG=false
+```
+
+Then in Dokploy:
+- Settings → Environment Variables → Import from file
+- Upload `.env.production`
+
+---
+
+### 3. Repository Setup
+
+1. **Connect Your Git Repository**:
+   - In Dokploy, create a new application
+   - Choose "Docker Compose"
+   - Connect your Git repository:
+     - **Repository URL**: `https://gitea.romfast.ro/romfast/roa2web.git`
+     - **Branch**: `main` (or your deployment branch)
+     - **Authentication**: Add Git credentials if private repo
+
+2. **Configure Build Settings**:
+   - **Dockerfile Path**: Not needed (using docker-compose.yml)
+   - **Docker Compose File**: `docker-compose.yml`
+   - **Build Context**: Repository root
+   - **Enable BuildKit**: ✅ (recommended for better caching)
+
+3. **Configure Deployment Settings**:
+   - **Auto-deploy**: Enable if you want automatic deployments on git push
+   - **Health Check**: Enable to verify services are running
+   - **Restart Policy**: `unless-stopped`
+
+---
+
+### 4. Deployment
+
+#### Initial Deployment
+
+1. **Pre-deployment Checklist**:
+   - ✅ SSH key is configured (Method A, B, or C)
+   - ✅ All environment variables are set
+   - ✅ Repository is connected and accessible
+   - ✅ Docker Compose file is valid
+
+2. **Start Deployment**:
+   - In Dokploy dashboard, click **Deploy**
+   - Monitor the deployment logs
+   - Look for these success indicators:
+     ```
+     ✅ Cloning Custom Git ...
+     ✅ Building services ...
+     ✅ Starting services ...
+     ✅ Health checks passing ...
+     ```
+
+3. **Expected Build Time**:
+   - First deployment: 5-10 minutes (depending on network and CPU)
+   - Subsequent deployments: 2-5 minutes (with caching)
+
+#### Deployment Stages
+
+1. **Clone Repository**:
+   ```
+   Cloning Custom Git https://...@gitea.romfast.ro/romfast/roa2web.git
+   ```
+
+2. **Build Images**:
+   - `roa-ssh-tunnel`: SSH tunnel container (~1 min)
+   - `roa-backend`: FastAPI backend (~3 min)
+   - `roa-frontend`: Vue.js frontend (~4 min)
+   - `roa-gateway`: Nginx gateway (~1 min)
+   - `roa-telegram-bot`: Telegram bot (~2 min)
+
+3. **Start Services**:
+   - Redis starts first
+   - SSH tunnel starts and establishes connection
+   - Backend waits for SSH tunnel health check
+   - Frontend starts
+   - Nginx gateway starts and routes traffic
+   - Telegram bot starts last
+
+4. **Health Checks**:
+   - Each service runs its health check
+   - Deployment succeeds when all health checks pass
+
+---
+
+## Post-Deployment
+
+### Verify Deployment
+
+1. **Check Service Status**:
+   - In Dokploy, navigate to **Containers**
+   - Verify all services are "Running" (green status):
+     - `roa-gateway` (Nginx)
+     - `roa-backend` (FastAPI)
+     - `roa-frontend` (Vue.js)
+     - `roa-ssh-tunnel` (SSH)
+     - `roa-redis` (Redis)
+     - `roa-telegram-bot` (Telegram)
+
+2. **Check Logs**:
+   ```bash
+   # In Dokploy UI, click on each container to view logs
+
+   # SSH Tunnel should show:
+   [INFO] SSH tunnel established: localhost:1526 -> 10.0.20.36:1521
+   [INFO] Tunnel is active and healthy
+
+   # Backend should show:
+   INFO:     Application startup complete.
+   INFO:     Uvicorn running on http://0.0.0.0:8000
+
+   # Frontend should show:
+   VITE v5.x ready in XXX ms
+
+   # Nginx should show:
+   nginx: [notice] start worker processes
+   ```
+
+3. **Test Endpoints**:
+
+   **Health Check**:
+   ```bash
+   curl https://your-domain.com/health
+   # Expected: {"status":"healthy"}
+   ```
+
+   **API Health**:
+   ```bash
+   curl https://your-domain.com/api/health
+   # Expected: {"status":"ok","database":"connected"}
+   ```
+
+   **Frontend**:
+   - Open `https://your-domain.com` in browser
+   - You should see the login page
+
+4. **Test Authentication**:
+   ```bash
+   curl -X POST https://your-domain.com/api/auth/login \
+     -H "Content-Type: application/json" \
+     -d '{"username":"test_user","password":"test_password"}'
+
+   # Expected: {"access_token":"eyJ...","token_type":"bearer"}
+   ```
+
+5. **Test Database Connection**:
+   ```bash
+   # Check SSH tunnel logs
+   docker logs roa-ssh-tunnel
+
+   # Should show successful tunnel establishment
+   # Should show periodic health checks passing
+   ```
+
+### Configure DNS and SSL
+
+1. **DNS Setup**:
+   - Point your domain to Dokploy server IP
+   - Add A record: `roa2web.yourdomain.com` → `<dokploy-server-ip>`
+
+2. **SSL Certificate** (if using custom domain):
+   - Dokploy typically handles SSL automatically via Let's Encrypt
+   - Or configure in `nginx/ssl/` directory
+   - Verify SSL: `https://www.ssllabs.com/ssltest/`
+
+3. **Update Environment Variables**:
+   - Set `DOMAIN=roa2web.yourdomain.com`
+   - Set `SSL_EMAIL=admin@yourdomain.com`
+   - Redeploy if needed
+
+### Configure Telegram Bot (Optional)
+
+1. **Test Bot**:
+   - Open Telegram
+   - Search for your bot: `@your_bot_name`
+   - Send `/start`
+   - Should receive welcome message
+
+2. **Link Account**:
+   - Login to web app
+   - Go to Settings → Telegram Integration
+   - Click "Generate Link Code"
+   - Copy the 8-character code
+   - Send to Telegram bot: `/start ABC123XY`
+   - Verify account is linked
+
+3. **Test Commands**:
+   ```
+   /help - Show available commands
+   /companies - List accessible companies
+   /dashboard - View financial dashboard
+   ```
+
+---
+
+## Monitoring and Maintenance
+
+### Monitor Services
+
+1. **Dokploy Dashboard**:
+   - View real-time container status
+   - Monitor CPU/Memory/Disk usage
+   - Check logs for errors
+
+2. **Health Checks**:
+   - Automatic health checks every 30 seconds
+   - Failed health checks trigger alerts
+   - Configure notifications in Dokploy settings
+
+3. **Logging**:
+   - Centralized logs in Dokploy UI
+   - Filter by service, time, log level
+   - Export logs for analysis
+
+### Backup Strategy
+
+1. **Database Backups** (Oracle):
+   - Handled by your Oracle DBA
+   - SSH tunnel only provides access, doesn't store data
+
+2. **Telegram Bot Database** (SQLite):
+   ```bash
+   # Backup SQLite database
+   docker exec roa-telegram-bot cp /app/data/telegram_bot.db /app/data/backup/
+
+   # Download backup
+   docker cp roa-telegram-bot:/app/data/backup/telegram_bot.db ./telegram_backup.db
+   ```
+
+3. **Configuration Backups**:
+   - Environment variables: Export from Dokploy
+   - Docker Compose: Keep in Git
+   - SSH keys: Store securely offline
+
+### Update and Rollback
+
+1. **Update Application**:
+   ```bash
+   # Push changes to git
+   git add .
+   git commit -m "Update feature X"
+   git push origin main
+
+   # In Dokploy, click "Redeploy"
+   # Or enable auto-deploy for automatic updates
+   ```
+
+2. **Rollback to Previous Version**:
+   - In Dokploy → Deployments → History
+   - Find previous successful deployment
+   - Click "Rollback"
+   - Confirm rollback
+
+3. **Zero-Downtime Updates**:
+   - Dokploy handles rolling updates automatically
+   - Old containers stay running until new ones are healthy
+   - Health checks ensure smooth transitions
+
+### Scaling
+
+1. **Horizontal Scaling** (Multiple Instances):
+   ```yaml
+   # In docker-compose.yml
+   roa-backend:
+     deploy:
+       replicas: 3  # Run 3 backend instances
+   ```
+
+2. **Vertical Scaling** (More Resources):
+   ```yaml
+   roa-backend:
+     deploy:
+       resources:
+         limits:
+           cpus: '2.0'
+           memory: 2G
+   ```
+
+3. **Load Balancing**:
+   - Nginx gateway handles load balancing automatically
+   - Distributes traffic across backend replicas
+   - Health checks ensure traffic goes to healthy instances
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. SSH Tunnel Connection Failed
+
+**Error**:
+```
+[ERROR] SSH connection failed: Permission denied (publickey)
+```
+
+**Solutions**:
+
+a. **Verify SSH Key**:
+```bash
+# Check key exists and has correct permissions
+docker exec roa-ssh-tunnel ls -l /home/tunnel/.ssh/roa_oracle_server
+# Expected: -rw------- 1 tunnel tunnel
+
+# Test SSH connection manually
+docker exec roa-ssh-tunnel ssh -i /home/tunnel/.ssh/roa_oracle_server \
+    -p 22122 roa2web@83.103.197.79 "echo 'Connected'"
+```
+
+b. **Verify SSH Key Format**:
+```bash
+# Key should start with:
+# -----BEGIN OPENSSH PRIVATE KEY-----
+# or
+# -----BEGIN RSA PRIVATE KEY-----
+
+# Check key format
+head -1 ./ssh-tunnel/secrets/roa_oracle_server
+```
+
+c. **Check Remote Server**:
+- Verify public key is in `~/.ssh/authorized_keys` on remote server
+- Verify SSH service is running on port 22122
+- Check firewall allows connections from Dokploy server IP
+
+#### 2. Oracle Database Connection Failed
+
+**Error**:
+```
+ORA-12170: TNS:Connect timeout occurred
+```
+
+**Solutions**:
+
+a. **Verify SSH Tunnel is Running**:
+```bash
+# Check tunnel health
+curl http://<dokploy-domain>/api/health
+
+# Check tunnel logs
+docker logs roa-ssh-tunnel
+
+# Should show: "SSH tunnel established"
+```
+
+b. **Test Oracle Connection**:
+```bash
+# From backend container
+docker exec roa-backend python -c "
+import oracledb
+conn = oracledb.connect(
+    user='CONTAFIN_ORACLE',
+    password='${ORACLE_PASSWORD}',
+    dsn='roa-ssh-tunnel:1526/ROA'
+)
+print('Connected successfully')
+conn.close()
+"
+```
+
+c. **Check Environment Variables**:
+```bash
+docker exec roa-backend env | grep ORACLE
+# Verify all ORACLE_* variables are set correctly
+```
+
+#### 3. Frontend Not Loading
+
+**Error**:
+```
+502 Bad Gateway
+```
+
+**Solutions**:
+
+a. **Check Frontend Container**:
+```bash
+# View frontend logs
+docker logs roa-frontend
+
+# Verify container is running
+docker ps | grep roa-frontend
+```
+
+b. **Check Nginx Configuration**:
+```bash
+# Test nginx config
+docker exec roa-gateway nginx -t
+
+# View nginx logs
+docker logs roa-gateway
+```
+
+c. **Verify Network**:
+```bash
+# Check containers can communicate
+docker exec roa-gateway ping roa-frontend
+docker exec roa-gateway ping roa-backend
+```
+
+#### 4. Backend API Errors
+
+**Error**:
+```
+{"detail":"Internal server error"}
+```
+
+**Solutions**:
+
+a. **Check Backend Logs**:
+```bash
+docker logs roa-backend --tail 100
+```
+
+b. **Check Database Connection**:
+```bash
+# Test database query
+docker exec roa-backend python -c "
+from app.database import oracle_pool
+async def test():
+    async with oracle_pool.get_connection() as conn:
+        cursor = conn.cursor()
+        cursor.execute('SELECT 1 FROM DUAL')
+        print(cursor.fetchone())
+import asyncio
+asyncio.run(test())
+"
+```
+
+c. **Check JWT Configuration**:
+```bash
+docker exec roa-backend env | grep JWT
+# Verify JWT_SECRET_KEY is set
+```
+
+#### 5. Telegram Bot Not Responding
+
+**Error**:
+- Bot doesn't respond to commands
+
+**Solutions**:
+
+a. **Check Bot Container**:
+```bash
+# View bot logs
+docker logs roa-telegram-bot --tail 100
+
+# Check if bot is running
+docker ps | grep telegram-bot
+```
+
+b. **Verify Token**:
+```bash
+# Check token is set
+docker exec roa-telegram-bot env | grep TELEGRAM_BOT_TOKEN
+
+# Test token validity
+curl https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe
+```
+
+c. **Check Backend Connection**:
+```bash
+# Test internal API
+docker exec roa-telegram-bot curl http://localhost:8002/internal/health
+
+# Test backend connection
+docker exec roa-telegram-bot curl http://roa-backend:8000/health
+```
+
+#### 6. Environment Variables Not Loading
+
+**Error**:
+```
+The "ORACLE_PASSWORD" variable is not set. Defaulting to a blank string.
+```
+
+**Solutions**:
+
+a. **Set in Dokploy UI**:
+- Go to Settings → Environment Variables
+- Add missing variable
+- Redeploy
+
+b. **Check Variable Names**:
+- Ensure no typos in variable names
+- Variables are case-sensitive
+- No leading/trailing spaces
+
+c. **Use .env File**:
+- Create `.env` in project root
+- Import via Dokploy UI
+- Redeploy
+
+#### 7. Build Failures
+
+**Error**:
+```
+failed to solve: failed to calculate checksum
+```
+
+**Solutions**:
+
+a. **Clear Build Cache**:
+- In Dokploy → Settings → Advanced
+- Click "Clear Build Cache"
+- Redeploy
+
+b. **Check Dockerfile**:
+```bash
+# Validate Dockerfiles locally
+docker build -t test-backend ./reports-app/backend
+docker build -t test-frontend ./reports-app/frontend
+docker build -t test-tunnel ./ssh-tunnel
+```
+
+c. **Check File Paths**:
+- Verify COPY paths in Dockerfiles
+- Ensure files exist in repository
+- Check .dockerignore isn't excluding needed files
+
+### Getting Help
+
+If issues persist:
+
+1. **Check Logs**:
+   ```bash
+   # Get all container logs
+   docker-compose logs > deployment_logs.txt
+   ```
+
+2. **Export Configuration**:
+   ```bash
+   # Export environment variables
+   # (redact sensitive values before sharing)
+   docker exec roa-backend env > backend_env.txt
+   ```
+
+3. **Contact Support**:
+   - Include: logs, error messages, steps to reproduce
+   - Redact: passwords, tokens, API keys
+   - Provide: Dokploy version, OS, Docker version
+
+4. **Community Resources**:
+   - Dokploy documentation: https://docs.dokploy.com
+   - ROA2WEB repository issues
+   - Docker documentation
+
+---
+
+## Security Best Practices
+
+1. **SSH Keys**:
+   - ✅ Use Ed25519 keys (more secure than RSA)
+   - ✅ Use unique keys for each environment
+   - ✅ Rotate keys periodically (every 6-12 months)
+   - ✅ Never commit private keys to public repositories
+   - ✅ Use secrets management for production
+
+2. **Environment Variables**:
+   - ✅ Use strong, random JWT secret keys (32+ characters)
+   - ✅ Use complex Oracle passwords
+   - ✅ Don't log sensitive values
+   - ✅ Rotate credentials periodically
+
+3. **Network Security**:
+   - ✅ Use HTTPS/SSL for all external connections
+   - ✅ Restrict SSH access by IP if possible
+   - ✅ Use Dokploy's firewall features
+   - ✅ Keep all software updated
+
+4. **Container Security**:
+   - ✅ Run containers as non-root users (already configured)
+   - ✅ Use minimal base images (alpine)
+   - ✅ Scan images for vulnerabilities
+   - ✅ Keep Docker and Dokploy updated
+
+5. **Access Control**:
+   - ✅ Use strong Dokploy admin password
+   - ✅ Enable 2FA on Git accounts
+   - ✅ Limit who has deployment access
+   - ✅ Audit access logs regularly
+
+---
+
+## Performance Optimization
+
+1. **Enable Caching**:
+   - Use Redis for session storage
+   - Enable browser caching in Nginx
+   - Use Docker build cache (BuildKit)
+
+2. **Resource Limits**:
+   ```yaml
+   services:
+     roa-backend:
+       deploy:
+         resources:
+           limits:
+             cpus: '1.0'
+             memory: 1G
+           reservations:
+             cpus: '0.5'
+             memory: 512M
+   ```
+
+3. **Database Connection Pooling**:
+   - Already configured in `shared/database/oracle_pool.py`
+   - Default: 5 min connections, 20 max connections
+   - Adjust based on load
+
+4. **Frontend Optimization**:
+   - Production build already includes:
+     - Minification
+     - Tree-shaking
+     - Code splitting
+     - Compression (gzip/brotli)
+
+---
+
+## Next Steps
+
+After successful deployment:
+
+1. ✅ **Monitor for 24-48 hours**:
+   - Check logs for errors
+   - Monitor resource usage
+   - Verify all features work
+
+2. ✅ **Set up Alerts**:
+   - Configure Dokploy notifications
+   - Set up health check alerts
+   - Monitor disk space
+
+3. ✅ **Plan Backup Strategy**:
+   - Schedule regular backups
+   - Test restore procedures
+   - Document backup locations
+
+4. ✅ **Document Custom Configuration**:
+   - Record any changes made
+   - Document environment-specific settings
+   - Share knowledge with team
+
+5. ✅ **Performance Testing**:
+   - Load test the application
+   - Optimize as needed
+   - Plan for scaling
+
+---
+
+## Additional Resources
+
+- **ROA2WEB Documentation**:
+  - `README.md` - Project overview
+  - `CLAUDE.md` - Development guide
+  - `DEPLOYMENT_GUIDE.md` - General deployment guide
+  - `ARCHITECTURE_SCHEMA.md` - Architecture details
+
+- **Dokploy Resources**:
+  - Documentation: https://docs.dokploy.com
+  - GitHub: https://github.com/dokploy/dokploy
+  - Community: Discord/Forums
+
+- **Docker Resources**:
+  - Docker Compose: https://docs.docker.com/compose/
+  - Docker Build: https://docs.docker.com/build/
+  - Best Practices: https://docs.docker.com/develop/dev-best-practices/
+
+---
+
+## Conclusion
+
+You should now have ROA2WEB successfully deployed on Dokploy! 🎉
+
+For questions or issues, refer to the troubleshooting section or check the ROA2WEB repository documentation.
+
+**Happy deploying!** 🚀

ssh-tunnel/.dockerignore

@@ -0,0 +1,68 @@
+# SSH Tunnel Docker Build - Ignore Patterns
+
+# Documentation (not needed in container)
+README_SSH_KEY.md
+docs/
+*.md
+!secrets/README.md
+
+# Git files
+.git/
+.gitignore
+.gitattributes
+
+# Development and test files
+*.test
+*.tmp
+*.temp
+*.log
+*.bak
+*.swp
+*.swo
+*~
+
+# IDE files
+.vscode/
+.idea/
+*.sublime-*
+
+# SSH files that should NOT be in the image
+# (only roa_oracle_server should be copied)
+secrets/*_test*
+secrets/*.pub
+secrets/*.pem
+secrets/*.key
+secrets/known_hosts
+secrets/config
+
+# Backup files
+*.backup
+*.orig
+*.old
+
+# OS files
+.DS_Store
+Thumbs.db
+._*
+
+# Python cache (if any scripts generate them)
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Temporary files
+temp/
+tmp/
+*.pid
+
+# Build artifacts
+*.tar
+*.tar.gz
+*.zip
+
+# Keep only what's needed for the build:
+# - Dockerfile (implicit)
+# - ssh_tunnel_docker.sh
+# - secrets/roa_oracle_server

ssh-tunnel/Dockerfile

@@ -18,7 +18,10 @@ RUN mkdir -p /home/tunnel/.ssh && \
     chown -R tunnel:tunnel /home/tunnel
 
 # Copy SSH key and set permissions (before switching to non-root user)
-COPY ../secrets/roa_oracle_server /home/tunnel/.ssh/roa_oracle_server
+# For production deployment (Dokploy/Docker), the SSH key should be:
+# 1. Placed in ssh-tunnel/secrets/roa_oracle_server before build, OR
+# 2. Provided via BuildKit secrets (see DOKPLOY_DEPLOYMENT.md)
+COPY secrets/roa_oracle_server /home/tunnel/.ssh/roa_oracle_server
 RUN chown tunnel:tunnel /home/tunnel/.ssh/roa_oracle_server && \
     chmod 600 /home/tunnel/.ssh/roa_oracle_server
 

ssh-tunnel/secrets/README.md

@@ -0,0 +1,109 @@
+# SSH Tunnel Secrets Directory
+
+This directory contains the SSH private key required for the SSH tunnel to connect to the Oracle database server.
+
+## Required File
+
+**File**: `roa_oracle_server`
+**Type**: SSH private key (RSA or ED25519)
+**Permissions**: 600 (read/write for owner only)
+
+## Setup Instructions
+
+### For Development (Local)
+
+If you already have the SSH key:
+```bash
+# Copy the SSH key to this directory
+cp /path/to/your/roa_oracle_server ./ssh-tunnel/secrets/
+
+# Set proper permissions
+chmod 600 ./ssh-tunnel/secrets/roa_oracle_server
+```
+
+### For Deployment (Dokploy/Production)
+
+#### Option 1: Manual File Upload (Simple)
+1. Before deploying, place the SSH key file in this directory
+2. Commit to your private repository (ensure the repo is private!)
+3. Deploy via Dokploy
+
+#### Option 2: Using Dokploy Secrets (Recommended)
+1. In Dokploy UI, go to your application settings
+2. Navigate to "Secrets" or "Environment Files" section
+3. Create a new secret named `SSH_KEY`
+4. Paste the contents of your SSH private key
+5. Update `docker-compose.yml` to mount this secret (see DOKPLOY_DEPLOYMENT.md)
+
+#### Option 3: Using Docker BuildKit Secrets (Most Secure)
+```bash
+# During build, pass the secret
+docker buildx build \
+  --secret id=ssh_key,src=/path/to/roa_oracle_server \
+  -t roa2web/ssh-tunnel:latest \
+  -f ssh-tunnel/Dockerfile \
+  ssh-tunnel/
+```
+
+## Security Notes
+
+⚠️ **IMPORTANT**:
+- This directory is **gitignored** by default to prevent accidental commits
+- **NEVER** commit the actual SSH private key to a public repository
+- Use secure methods (secrets management, encrypted storage) for production
+- Ensure proper file permissions (600) on the SSH key file
+
+## Generating a New SSH Key (if needed)
+
+If you need to generate a new SSH key pair:
+
+```bash
+# Generate ED25519 key (recommended, more secure and faster)
+ssh-keygen -t ed25519 -f ./ssh-tunnel/secrets/roa_oracle_server -C "roa2web-tunnel"
+
+# OR generate RSA key (if ED25519 not supported)
+ssh-keygen -t rsa -b 4096 -f ./ssh-tunnel/secrets/roa_oracle_server -C "roa2web-tunnel"
+
+# Set proper permissions
+chmod 600 ./ssh-tunnel/secrets/roa_oracle_server
+chmod 644 ./ssh-tunnel/secrets/roa_oracle_server.pub
+
+# Add the public key to the remote server's authorized_keys
+# (You'll need to manually add it to the server)
+cat ./ssh-tunnel/secrets/roa_oracle_server.pub
+```
+
+## Testing the SSH Connection
+
+Before building the Docker image, test the SSH connection:
+
+```bash
+ssh -i ./ssh-tunnel/secrets/roa_oracle_server \
+    -p 22122 \
+    roa2web@83.103.197.79 \
+    "echo 'SSH connection successful'"
+```
+
+## Troubleshooting
+
+### "Permission denied (publickey)" Error
+- Verify the SSH key is in the correct format
+- Check that the public key is added to the remote server's `~/.ssh/authorized_keys`
+- Ensure proper permissions on the key file (600)
+
+### "No such file or directory" During Docker Build
+- Make sure the file is named exactly `roa_oracle_server` (no extension)
+- Verify the file exists in `ssh-tunnel/secrets/` directory
+- Check that you're building from the repository root
+
+### Docker Build Fails with "COPY failed"
+- Ensure the build context includes the secrets directory
+- Verify the Dockerfile COPY path is correct: `COPY secrets/roa_oracle_server ...`
+- Check that the file is not empty
+
+## Support
+
+For more information about SSH tunnel setup and deployment, see:
+- `../README_SSH_KEY.md` - SSH key setup guide
+- `DOKPLOY_DEPLOYMENT.md` - Dokploy deployment guide (root directory)
+- `DEPLOYMENT_GUIDE.md` - General deployment guide (root directory)