diff --git a/README.md b/README.md index b4b10b6..4d19af6 100644 --- a/README.md +++ b/README.md @@ -128,7 +128,9 @@ The application supports multiple database backends. Choose the one that fits yo #### SQLite3 (Default - Development) -SQLite3 is the default database and requires no additional setup. It's perfect for development and single-user scenarios. +SQLite3 is the default database and requires no additional setup. It's perfect for development, testing, and single-user scenarios. + +**No installation required** - SQLite comes bundled with Python. **Configuration in `config/settings/development.py`:** ```python @@ -140,19 +142,49 @@ DATABASES = { } ``` +**Using DATABASE_URL in `.env`:** +```bash +DATABASE_URL=sqlite:///db.sqlite3 +``` + +**When to use SQLite:** +- ✅ Development and testing +- ✅ Single-user deployments +- ✅ Low-traffic personal projects +- ✅ Quick prototyping +- ✅ Embedded applications + +**When NOT to use SQLite:** +- ❌ Production with multiple concurrent users +- ❌ High-traffic websites +- ❌ Applications requiring network database access +- ❌ Heavy write operations + **Pros:** -- Zero configuration +- Zero configuration - works out of the box - No separate database server needed +- Lightweight and fast for small datasets - Perfect for development and testing +- Easy to backup (single file) **Cons:** - Not recommended for production with multiple users -- Limited concurrent write operations +- Limited concurrent write operations (can cause database locks) - No network access (local file only) +- Not suitable for high-traffic applications +- Limited scalability #### PostgreSQL (Recommended for Production) -PostgreSQL is the recommended database for production deployments. +PostgreSQL is the recommended database for production deployments. It offers the best combination of performance, features, and reliability for Django applications. + +**When to use PostgreSQL:** +- ✅ **Production environments** (highly recommended) +- ✅ Applications with multiple concurrent users +- ✅ Need for advanced features (JSONB, full-text search, etc.) +- ✅ Complex queries and data integrity requirements +- ✅ Scalability and performance are priorities +- ✅ Geographic data (PostGIS extension) **1. Install PostgreSQL:** ```bash @@ -161,6 +193,14 @@ sudo apt-get install postgresql postgresql-contrib libpq-dev # macOS brew install postgresql + +# Start PostgreSQL service +# Ubuntu/Debian: +sudo systemctl start postgresql +sudo systemctl enable postgresql + +# macOS: +brew services start postgresql ``` **2. Create database and user:** @@ -172,12 +212,20 @@ ALTER ROLE keepitgoing_user SET client_encoding TO 'utf8'; ALTER ROLE keepitgoing_user SET default_transaction_isolation TO 'read committed'; ALTER ROLE keepitgoing_user SET timezone TO 'UTC'; GRANT ALL PRIVILEGES ON DATABASE keepitgoing TO keepitgoing_user; + +-- For PostgreSQL 15+, also grant schema permissions: +\c keepitgoing +GRANT ALL ON SCHEMA public TO keepitgoing_user; \q ``` **3. Install Python driver:** ```bash +# For production use: pip install psycopg2-binary + +# For development/if psycopg2-binary fails: +# pip install psycopg2 ``` **4. Update settings:** @@ -197,6 +245,7 @@ DATABASES = { 'PASSWORD': 'your_secure_password', 'HOST': 'localhost', 'PORT': '5432', + 'CONN_MAX_AGE': 600, # Connection pooling } } ``` @@ -206,9 +255,38 @@ DATABASES = { python manage.py migrate ``` -#### MariaDB/MySQL +**6. Performance tuning (optional):** -MariaDB and MySQL are also supported for production use. +Edit `/etc/postgresql/[version]/main/postgresql.conf`: +```ini +# Adjust based on available RAM (25% of total RAM) +shared_buffers = 256MB + +# Effective cache size (50-75% of total RAM) +effective_cache_size = 1GB + +# Maintenance work memory +maintenance_work_mem = 64MB + +# Maximum connections +max_connections = 100 +``` + +Restart PostgreSQL: +```bash +sudo systemctl restart postgresql +``` + +#### MariaDB/MySQL (Alternative Production Database) + +MariaDB and MySQL are well-supported alternatives for production deployments. MariaDB is recommended over MySQL for better performance and features. + +**When to use MySQL/MariaDB:** +- ✅ Production environments with multiple users +- ✅ Applications requiring replication +- ✅ Teams familiar with MySQL ecosystem +- ✅ Need for specific MySQL features or tools +- ✅ Integration with existing MySQL infrastructure **1. Install MariaDB:** ```bash @@ -217,9 +295,23 @@ sudo apt-get install mariadb-server libmariadb-dev # macOS brew install mariadb + +# For MySQL instead of MariaDB: +# Ubuntu/Debian: sudo apt-get install mysql-server libmysqlclient-dev +# macOS: brew install mysql ``` -**2. Create database and user:** +**2. Secure installation (recommended):** +```bash +sudo mysql_secure_installation +# This will prompt you to: +# - Set root password +# - Remove anonymous users +# - Disallow root login remotely +# - Remove test database +``` + +**3. Create database and user:** ```bash sudo mysql CREATE DATABASE keepitgoing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; @@ -229,12 +321,16 @@ FLUSH PRIVILEGES; EXIT; ``` -**3. Install Python driver:** +**4. Install Python driver:** ```bash pip install mysqlclient + +# If mysqlclient installation fails, you can use PyMySQL as an alternative: +# pip install pymysql +# Then add to your settings: import pymysql; pymysql.install_as_MySQLdb() ``` -**4. Update settings:** +**5. Update settings:** Add to your `.env` file: ```bash @@ -259,11 +355,29 @@ DATABASES = { } ``` -**5. Run migrations:** +**6. Run migrations:** ```bash python manage.py migrate ``` +**Performance tuning (optional):** +Edit `/etc/mysql/mariadb.conf.d/50-server.cnf` (MariaDB) or `/etc/mysql/mysql.conf.d/mysqld.cnf` (MySQL): +```ini +[mysqld] +# Increase buffer pool size (adjust based on available RAM) +innodb_buffer_pool_size = 1G +# Improve connection handling +max_connections = 200 +# Enable query cache (MySQL 5.7 only, removed in MySQL 8.0) +query_cache_type = 1 +query_cache_size = 64M +``` + +Restart database: +```bash +sudo systemctl restart mariadb # or mysql +``` + #### Database Migration Between Backends To migrate data from one database to another: @@ -478,7 +592,14 @@ sudo apt install -y certbot python3-certbot-nginx #### Step 2: Database Setup +Choose your database backend. PostgreSQL is recommended for production. + +**Option A: PostgreSQL (Recommended for Production)** + ```bash +# Install PostgreSQL +sudo apt install -y postgresql postgresql-contrib libpq-dev + # Create PostgreSQL database and user sudo -u postgres psql << EOF CREATE DATABASE keepitgoing; @@ -491,6 +612,29 @@ GRANT ALL PRIVILEGES ON DATABASE keepitgoing TO keepitgoing_user; EOF ``` +**Option B: MySQL/MariaDB (Alternative Production Database)** + +```bash +# Install MariaDB +sudo apt install -y mariadb-server libmariadb-dev + +# Secure MariaDB installation +sudo mysql_secure_installation + +# Create database and user +sudo mysql << EOF +CREATE DATABASE keepitgoing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +CREATE USER 'keepitgoing_user'@'localhost' IDENTIFIED BY 'STRONG_PASSWORD_HERE'; +GRANT ALL PRIVILEGES ON keepitgoing.* TO 'keepitgoing_user'@'localhost'; +FLUSH PRIVILEGES; +EXIT; +EOF +``` + +**Option C: SQLite (Development/Testing Only)** + +No database server setup required. SQLite uses a local file and is configured automatically. **Not recommended for production with multiple users.** + #### Step 3: Application Setup ```bash @@ -508,7 +652,14 @@ source venv/bin/activate # Install dependencies pip install -r requirements.txt -pip install gunicorn psycopg2-binary +pip install gunicorn + +# Install database driver based on your choice from Step 2 +# For PostgreSQL: +pip install psycopg2-binary +# For MySQL/MariaDB: +# pip install mysqlclient +# For SQLite: no additional package needed # Create production environment file cat > .env << 'EOF' @@ -519,10 +670,19 @@ ALLOWED_HOSTS=tasks.firebugit.com,localhost,127.0.0.1 CSRF_TRUSTED_ORIGINS=https://tasks.firebugit.com SITE_DOMAIN=tasks.firebugit.com -# Database +# Database Configuration +# Choose ONE of the following based on your database from Step 2: + +# Option A: PostgreSQL (Recommended) DATABASE_URL=postgresql://keepitgoing_user:STRONG_PASSWORD_HERE@localhost:5432/keepitgoing -# Email Configuration (Gmail example) +# Option B: MySQL/MariaDB (Alternative) +# DATABASE_URL=mysql://keepitgoing_user:STRONG_PASSWORD_HERE@localhost:3306/keepitgoing + +# Option C: SQLite (Development/Testing only - Not for production!) +# DATABASE_URL=sqlite:///db.sqlite3 + +# Email Configuration (Gmail example - see Step 4 for other providers) EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend EMAIL_HOST=smtp.gmail.com EMAIL_PORT=587