chore(backend): update environment configuration and README for Docker

Author: Lasim

services/backend/.env.example

@@ -1,22 +1,33 @@
-# Database Configuration
-# Choose one: sqlite, turso
-DB_TYPE=sqlite
+# Server Configuration
+NODE_ENV=development
+PORT=3000
+HOST=localhost
 
-# SQLite Configuration (when DB_TYPE=sqlite)
-SQLITE_DB_PATH=persistent_data/database/deploystack.db
+# Frontend Integration
+# URL of your frontend application for CORS and redirects
+DEPLOYSTACK_FRONTEND_URL=http://localhost:5173
 
-# Turso Configuration (when DB_TYPE=turso)
-# Get these values from: https://docs.turso.tech/sdk/ts/quickstart
-# TURSO_DATABASE_URL=libsql://your-database-url
-# TURSO_AUTH_TOKEN=your-auth-token
+# Security
+# Required: 32+ character secret for encrypting cookies and global settings
+# Generate with: openssl rand -hex 32
+DEPLOYSTACK_ENCRYPTION_SECRET=your-32-character-secret-key-here-change-this
 
 # Logging Configuration
 # Available levels: trace, debug, info, warn, error, fatal
-# Default: info (production), debug (development)
-LOG_LEVEL=info
+# Default: debug (development), info (production)
+# LOG_LEVEL=debug
 
-# Other existing environment variables...
-NODE_ENV=development
-HOST=localhost
-PORT=3000
-COOKIE_SECRET=a-very-secret-and-strong-secret-for-cookies
+# Plugin System (Optional)
+# Custom path for loading plugins
+# PLUGINS_PATH=/path/to/custom/plugins
+
+# Database Configuration (Optional)
+# Note: Database configuration is primarily handled through the setup wizard at /setup
+# The database type and connection details are stored in persistent_data/db.selection.json
+# However, you can override with environment variables if needed:
+
+# Turso Database Configuration (Optional)
+# If you want to use Turso instead of SQLite, you can set these variables
+# Get these values from: https://turso.tech/
+# TURSO_DATABASE_URL=libsql://your-database-url.turso.io
+# TURSO_AUTH_TOKEN=your-turso-auth-token

services/backend/Dockerfile

@@ -16,8 +16,8 @@ COPY services/backend/dist ./dist
 RUN mkdir -p /shared/public/img/
 COPY services/shared/public/img/favicon.ico /shared/public/img/
 
-# Create data directory for SQLite database
-RUN mkdir -p /app/data
+# Create persistent_data directory structure
+RUN mkdir -p /app/persistent_data
 
 # Create a default .env file
 RUN echo "NODE_ENV=production" > .env && \

services/backend/README.md

@@ -15,13 +15,21 @@ A modular and extensible backend API for the DeployStack CI/CD platform, built w
 - **Logging**: Comprehensive request logging with request IDs and timing
 - **Developer-friendly**: Pretty logging in development, production-ready in production
 
-## 🚀 Run
+## 🚀 Quick Start with Docker
 
 ```bash
+# Run with Docker (using docker-compose recommended)
+docker-compose up -d
+
+# Or run standalone with volume for data persistence
 docker run -it -p 3000:3000 \
-  -e FOO=bar22 \
-  -v $(pwd)/data:/app/data \
+  -e NODE_ENV=production \
+  -e DEPLOYSTACK_ENCRYPTION_SECRET=your-32-character-secret-key-here \
+  -v deploystack_data:/app/persistent_data \
   deploystack/backend:latest
+
+# Access the setup wizard at http://localhost:3000
+# (or http://localhost:8080 if using the full docker-compose stack)
 ```
 
 ## 📋 Prerequisites
@@ -31,20 +39,44 @@ docker run -it -p 3000:3000 \
 
 ## 🛠️ Installation
 
+### Development Setup
+
 ```bash
 # Clone the repository
-git clone https://github.com/deploystack/deploystack.git
+git clone https://github.com/deploystackio/deploystack.git
 cd deploystack
 
 # Navigate to backend directory
 cd services/backend
 
 # Install dependencies
 npm install
+
+# Create .env file (see Environment Variables section)
+cp .env.example .env  # Or create manually
+
+# Start development server
+npm run dev
+
+# Access at http://localhost:3000
+```
+
+### Production Setup with Docker
+
+```bash
+# Using Docker Compose (recommended)
+git clone https://github.com/deploystackio/deploystack.git
+cd deploystack
+docker-compose up -d
+
+# Access frontend at http://localhost:8080
+# Backend API at http://localhost:3000
 ```
 
 ## 🚀 Usage
 
+### Development Commands
+
 ```bash
 # Run in development mode (with live reloading)
 npm run dev
@@ -57,94 +89,73 @@ npm run start
 
 # Lint and fix TypeScript files
 npm run lint
-```
 
-## 🧱 Project Structure
+# Database migrations
+npm run db:generate  # Generate new migrations
+npm run db:up        # Apply migrations
 
-```bash
-services/backend/
-├── src/
-│   ├── api/            # API route handlers
-│   ├── db/             # Database configuration and schema
-│   │   ├── config.ts   # Database connection setup
-│   │   ├── index.ts    # Database exports
-│   │   ├── migrations.ts # Migration management
-│   │   └── schema.ts   # Database schema definitions
-│   ├── email/          # Email system (NEW)
-│   │   ├── templates/  # Pug email templates
-│   │   │   ├── layouts/    # Base layout components
-│   │   │   │   ├── base.pug    # Main email layout
-│   │   │   │   ├── header.pug  # Email header
-│   │   │   │   └── footer.pug  # Email footer
-│   │   │   ├── welcome.pug     # Welcome email template
-│   │   │   ├── password-reset.pug # Password reset template
-│   │   │   └── notification.pug   # General notification template
-│   │   ├── emailService.ts     # Main email service
-│   │   ├── templateRenderer.ts # Pug template renderer
-│   │   ├── types.ts           # Email type definitions
-│   │   ├── example.ts         # Usage examples
-│   │   └── index.ts           # Email module exports
-│   ├── fastify/        # Fastify configuration
-│   │   ├── config/     # Fastify setup
-│   │   ├── hooks/      # Request/response hooks
-│   │   └── plugins/    # Fastify plugins
-│   ├── global-settings/ # Global configuration system
-│   │   ├── github-oauth.ts # GitHub OAuth settings
-│   │   ├── smtp.ts     # SMTP email settings
-│   │   ├── types.ts    # Global settings types
-│   │   └── index.ts    # Settings initialization
-│   ├── hooks/          # Authentication hooks
-│   ├── lib/            # External library integrations
-│   │   └── lucia.ts    # Lucia authentication setup
-│   ├── middleware/     # Request middleware
-│   ├── plugin-system/  # Plugin architecture
-│   ├── plugins/        # Available plugins
-│   ├── routes/         # API route definitions
-│   │   ├── auth/       # Authentication routes
-│   │   ├── db/         # Database management routes
-│   │   ├── globalSettings/ # Settings management routes
-│   │   ├── roles/      # Role management routes
-│   │   └── users/      # User management routes
-│   ├── services/       # Business logic services
-│   │   ├── globalSettingsService.ts # Settings service
-│   │   ├── roleService.ts           # Role management
-│   │   ├── teamService.ts           # Team management
-│   │   └── userService.ts           # User management
-│   ├── types/          # TypeScript type definitions
-│   ├── utils/          # Utility functions
-│   │   ├── banner.ts   # Startup banner
-│   │   └── encryption.ts # Encryption utilities
-│   ├── server.ts       # Server configuration
-│   └── index.ts        # Application entry point
-├── drizzle/            # Database migrations
-├── persistent_data/    # Persistent application data
-├── tests/              # Test files
-├── .env                # Environment variables (not in version control)
-├── DB.md               # Database documentation
-├── GLOBAL_SETTINGS.md  # Global settings documentation
-├── Mail.md             # Email system documentation (NEW)
-├── PLUGINS.md          # Plugin system documentation
-├── ROLES.md            # Role management documentation
-├── SECURITY.md         # Security documentation
-├── package.json        # Package dependencies and scripts
-└── tsconfig.json       # TypeScript configuration
+# API documentation
+npm run api:spec      # Generate OpenAPI spec
 ```
 
+### Initial Setup
+
+1. **First Run**: Navigate to `/setup` in your browser
+2. **Choose Database**: Select SQLite (default) or Turso
+3. **Create Admin**: Set up your administrator account
+4. **Configure Settings**: Access Global Settings to configure email, features, etc.
+
 ## 💾 Persistent Data
 
-The `services/backend/persistent_data/` directory is designated for storing all data that needs to persist across application restarts or deployments.
+All persistent data is stored in the `persistent_data/` directory, which maintains the same structure across development and production environments.
+
+### Directory Structure
+
+```
+persistent_data/
+├── database/
+│   └── deploystack.db     # SQLite database (if using SQLite)
+└── db.selection.json       # Database type configuration
+```
+
+### Environment-Specific Locations
+
+**Development (Local):**
+- Location: `services/backend/persistent_data/`
+- Created automatically when running `npm run dev`
+- Direct file system access
 
-**Purpose:**
+**Production (Docker):**
+- Location: `/app/persistent_data/` (inside container)
+- Mounted as Docker volume: `deploystack_backend_persistent`
+- Persists data between container restarts
 
-- To provide a single, consistent location for all persistent backend data.
-- When developing backend features that require data persistence (e.g., database files, configuration files that should not be in version control but are generated/modified at runtime), use this directory exclusively.
+### Backup Strategies
 
-**Examples of data stored here:**
+**Docker Volume Backup:**
+```bash
+# Create backup
+docker run --rm -v deploystack_backend_persistent:/data \
+  -v $(pwd):/backup alpine \
+  tar czf /backup/deploystack-backup-$(date +%Y%m%d).tar.gz /data
+
+# Restore backup
+docker run --rm -v deploystack_backend_persistent:/data \
+  -v $(pwd):/backup alpine \
+  tar xzf /backup/deploystack-backup-20250108.tar.gz -C /
+```
 
-- SQLite database file (e.g., `persistent_data/database/deploystack.db`)
-- Database selection configuration (e.g., `persistent_data/db.selection.json`)
+**Local Development Backup:**
+```bash
+# Create backup
+tar czf deploystack-backup-$(date +%Y%m%d).tar.gz \
+  services/backend/persistent_data/
+
+# Restore backup
+tar xzf deploystack-backup-20250108.tar.gz
+```
 
-This ensures that persistent data is managed in a predictable way and is not scattered across the project.
+**Important:** Always backup the entire `persistent_data/` directory/volume, not just the database file, as it contains critical configuration.
 
 ## 📧 Email System
 
@@ -192,6 +203,7 @@ NODE_ENV=development
 PORT=3000
 HOST=localhost
 LOG_LEVEL=info
+DEPLOYSTACK_FRONTEND_URL=http://localhost:5173  # Frontend URL for CORS and redirects
 DEPLOYSTACK_ENCRYPTION_SECRET=your-32-character-secret-key-here  # Required for global settings encryption
 ```