Merge pull request #361 from Worklenz/imp/docker-production-setup-and-fixes

Imp/docker production setup and fixes

Author: chamikaJ

.env.example

@@ -0,0 +1,256 @@
+# ============================================================================
+# Worklenz Self-Hosted Configuration
+# ============================================================================
+# Copy this file to .env and configure according to your needs
+# Required fields are marked with (REQUIRED)
+# ============================================================================
+
+# ============================================================================
+# DEPLOYMENT MODE
+# ============================================================================
+# Choose deployment mode:
+# - express: All services bundled (PostgreSQL, Redis, MinIO included) - Recommended for most users
+# - advanced: Use external services (AWS S3, Azure Blob, external PostgreSQL)
+DEPLOYMENT_MODE=express
+
+# ============================================================================
+# DOMAIN AND URL CONFIGURATION
+# ============================================================================
+# Your domain name (e.g., worklenz.example.com)
+# For localhost testing: localhost
+# For production: your-domain.com
+DOMAIN=localhost
+
+# Base URL for the API (used by frontend to connect to backend)
+# For production with HTTPS: https://your-domain.com
+# For localhost HTTP: http://localhost
+VITE_API_URL=http://localhost
+
+# WebSocket URL for real-time features
+# For production with HTTPS: wss://your-domain.com
+# For localhost: ws://localhost
+VITE_SOCKET_URL=ws://localhost
+
+# Frontend URL (used by backend for CORS and redirects)
+# Should match your domain URL
+FRONTEND_URL=http://localhost
+
+# CORS Configuration
+# For development: * (allows all origins)
+# For production: your-domain.com or https://your-domain.com
+SERVER_CORS=*
+SOCKET_IO_CORS=http://localhost
+
+# ============================================================================
+# PORT CONFIGURATION
+# ============================================================================
+# Ports exposed to the host machine
+HTTP_PORT=80
+HTTPS_PORT=443
+
+# ============================================================================
+# DATABASE CONFIGURATION (PostgreSQL)
+# ============================================================================
+DB_NAME=worklenz_db
+DB_USER=postgres
+# Database password (REQUIRED) - Change this!
+DB_PASSWORD=CHANGE_THIS_SECURE_PASSWORD_123
+DB_MAX_CLIENTS=50
+USE_PG_NATIVE=false
+
+# Advanced: External PostgreSQL (only if not using bundled PostgreSQL)
+# DB_HOST=your-postgres-host.com
+# DB_PORT=5432
+
+# ============================================================================
+# SECURITY SECRETS
+# ============================================================================
+# Generate secure random strings with: openssl rand -hex 32
+
+# Session Secret (REQUIRED)
+SESSION_SECRET=CHANGE_THIS_TO_RANDOM_HEX_STRING_32_CHARS
+
+# Cookie Secret (REQUIRED)
+COOKIE_SECRET=CHANGE_THIS_TO_RANDOM_HEX_STRING_32_CHARS
+
+# JWT Secret (REQUIRED)
+JWT_SECRET=CHANGE_THIS_TO_RANDOM_HEX_STRING_32_CHARS
+
+# Session cookie name
+SESSION_NAME=worklenz.sid
+
+# ============================================================================
+# REDIS CONFIGURATION
+# ============================================================================
+# Redis password (REQUIRED for Express mode)
+REDIS_PASSWORD=CHANGE_THIS_REDIS_PASSWORD
+REDIS_DB=0
+
+# ============================================================================
+# STORAGE CONFIGURATION
+# ============================================================================
+# Storage provider: s3 (for MinIO/AWS S3), azure (for Azure Blob)
+STORAGE_PROVIDER=s3
+
+# ----------------------------------------------------------------------------
+# MinIO Configuration (Express Mode - Default, S3-compatible)
+# ----------------------------------------------------------------------------
+AWS_REGION=us-east-1
+AWS_BUCKET=worklenz-bucket
+AWS_ACCESS_KEY_ID=minioadmin
+# MinIO secret access key (REQUIRED) - Change this!
+AWS_SECRET_ACCESS_KEY=CHANGE_THIS_MINIO_PASSWORD
+S3_URL=http://minio:9000
+MINIO_BROWSER=on
+
+# ----------------------------------------------------------------------------
+# AWS S3 Configuration (Advanced Mode - External S3)
+# ----------------------------------------------------------------------------
+# Uncomment and configure if using real AWS S3 (set STORAGE_PROVIDER=s3)
+# AWS_REGION=us-east-1
+# AWS_BUCKET=your-worklenz-bucket
+# AWS_ACCESS_KEY_ID=your_aws_access_key_id
+# AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
+# S3_URL=  # Leave empty for AWS S3 (not MinIO)
+
+# ----------------------------------------------------------------------------
+# Azure Blob Storage Configuration (Advanced Mode)
+# ----------------------------------------------------------------------------
+# Uncomment and configure if using Azure Blob (set STORAGE_PROVIDER=azure)
+# AZURE_STORAGE_ACCOUNT_NAME=your_storage_account
+# AZURE_STORAGE_CONTAINER=worklenz-uploads
+# AZURE_STORAGE_ACCOUNT_KEY=your_storage_account_key
+# AZURE_STORAGE_URL=https://your_account.blob.core.windows.net
+
+# ============================================================================
+# GOOGLE OAUTH (Optional)
+# ============================================================================
+# Configure if you want to enable Google login
+# Get credentials from: https://console.cloud.google.com/apis/credentials
+# GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+# GOOGLE_CLIENT_SECRET=your-client-secret
+# GOOGLE_CALLBACK_URL=http://localhost/api/auth/google/callback
+# VITE_ENABLE_GOOGLE_LOGIN=true
+
+# ============================================================================
+# EMAIL CONFIGURATION (Optional)
+# ============================================================================
+# Configure if you want to enable email notifications
+# Note: Worklenz uses AWS SES for email, configure your SES credentials
+
+ENABLE_EMAIL_CRONJOBS=false
+# CONTACT_US_EMAIL=contact@your-domain.com
+
+# For AWS SES, use the AWS credentials above or configure separate SES credentials
+# AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are also used for SES
+# AWS_REGION should be your SES region
+
+# ============================================================================
+# GOOGLE RECAPTCHA (Optional)
+# ============================================================================
+# Configure if you want to enable reCAPTCHA protection
+# Get credentials from: https://www.google.com/recaptcha/admin
+# GOOGLE_CAPTCHA_SECRET_KEY=your-secret-key
+# GOOGLE_CAPTCHA_PASS_SCORE=0.8
+# VITE_ENABLE_RECAPTCHA=true
+# VITE_RECAPTCHA_SITE_KEY=your-site-key
+
+# ============================================================================
+# APPLICATION CONFIGURATION
+# ============================================================================
+# Application title (shown in browser tab)
+VITE_APP_TITLE=Worklenz
+
+# Enable survey modal (user feedback)
+VITE_ENABLE_SURVEY_MODAL=false
+
+# Timezone
+TZ=UTC
+
+# ============================================================================
+# BACKUP CONFIGURATION
+# ============================================================================
+# Backup retention in days (backups older than this are auto-deleted)
+BACKUP_RETENTION_DAYS=30
+
+# ============================================================================
+# SSL/TLS CONFIGURATION
+# ============================================================================
+# Enable SSL with Let's Encrypt (true/false)
+ENABLE_SSL=false
+
+# Email for Let's Encrypt notifications (required if ENABLE_SSL=true)
+# LETSENCRYPT_EMAIL=admin@your-domain.com
+
+# ============================================================================
+# DOCKER CONFIGURATION
+# ============================================================================
+# Docker Hub username (for building and pushing custom images)
+# Pre-built images are available at: chamikajaycey/worklenz-backend and chamikajaycey/worklenz-frontend
+DOCKER_USERNAME=chamikajaycey
+
+# ============================================================================
+# ADVANCED CONFIGURATION (Usually no need to change)
+# ============================================================================
+# Backend port inside container
+PORT=3000
+
+# Node environment
+NODE_ENV=production
+
+# ============================================================================
+# CONFIGURATION GUIDE
+# ============================================================================
+#
+# QUICK START (Express Mode - Recommended):
+# ==========================================
+# 1. Copy this file: cp .env.example .env
+# 2. Change these required passwords:
+#    - DB_PASSWORD
+#    - SESSION_SECRET (generate with: openssl rand -hex 32)
+#    - COOKIE_SECRET (generate with: openssl rand -hex 32)
+#    - JWT_SECRET (generate with: openssl rand -hex 32)
+#    - AWS_SECRET_ACCESS_KEY (MinIO password)
+#    - REDIS_PASSWORD
+# 3. For localhost: Keep DOMAIN=localhost and URLs as http://localhost
+# 4. For production domain: Set DOMAIN, update all URLs to https://your-domain.com
+# 5. Run: docker compose --profile express up -d
+#
+# PRODUCTION DEPLOYMENT WITH CUSTOM DOMAIN:
+# ==========================================
+# 1. Set DOMAIN=your-domain.com
+# 2. Update URLs:
+#    VITE_API_URL=https://your-domain.com
+#    VITE_SOCKET_URL=wss://your-domain.com
+#    FRONTEND_URL=https://your-domain.com
+#    SERVER_CORS=https://your-domain.com
+#    SOCKET_IO_CORS=https://your-domain.com
+# 3. Enable SSL:
+#    ENABLE_SSL=true
+#    LETSENCRYPT_EMAIL=your-email@domain.com
+# 4. Point your domain's DNS A record to your server IP
+# 5. Run: docker compose --profile express --profile ssl up -d
+#
+# ADVANCED MODE (External Services):
+# ===================================
+# 1. Set DEPLOYMENT_MODE=advanced
+# 2. For AWS S3:
+#    - Set STORAGE_PROVIDER=s3
+#    - Configure AWS_* variables with real AWS credentials
+#    - Set S3_URL="" (empty for real S3, not MinIO)
+# 3. For Azure Blob:
+#    - Set STORAGE_PROVIDER=azure
+#    - Configure AZURE_* variables
+# 4. For external PostgreSQL:
+#    - Uncomment and set DB_HOST, DB_PORT
+# 5. Services with "express" profile (Redis, MinIO) won't start
+#
+# GOOGLE LOGIN SETUP:
+# ===================
+# 1. Go to: https://console.cloud.google.com/apis/credentials
+# 2. Create OAuth 2.0 credentials
+# 3. Add authorized redirect URI: https://your-domain.com/api/auth/google/callback
+# 4. Set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_CALLBACK_URL
+# 5. Set VITE_ENABLE_GOOGLE_LOGIN=true
+#
+# ============================================================================

.gitignore

@@ -78,4 +78,9 @@ $RECYCLE.BIN/
 # TypeScript
 *.tsbuildinfo
 
-
+# Docker & SSL
+nginx/ssl/
+backups/
+*.bak
+*.tmp
+nginx/conf.d/*.bak

CONTRIBUTING.md

@@ -3,6 +3,24 @@
 Thanks for your interest in contributing to Worklenz!
 
 We truly appreciate your willingness to invest your time and effort in helping us improve Worklenz.
+
+## Getting Started
+
+To get started with development:
+
+1. **Quick Setup with Docker (Recommended):**
+   ```bash
+   git clone https://github.com/Worklenz/worklenz.git
+   cd worklenz
+   ./quick-setup.sh
+   ```
+
+2. **Manual Development Setup:**
+   See [SETUP_THE_PROJECT.md](SETUP_THE_PROJECT.md) for detailed instructions on setting up the development environment.
+
+3. **Docker Management:**
+   Use `./manage.sh` for common operations like viewing logs, creating backups, and managing services.
+
 ## Code of Conduct
 
 We have adopted a Code of Conduct to ensure a welcoming and inclusive environment for everyone. Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) when participating in this project.