making the requested changes

Author: LucasQR

README.md

@@ -115,6 +115,25 @@ DEFAULT_RATE_LIMIT_LIMIT=10      # Default: 10 requests
 DEFAULT_RATE_LIMIT_PERIOD=3600   # Default: 3600 seconds (1 hour)
 ```
 
+### CORS Configuration
+
+Configure Cross-Origin Resource Sharing for your frontend:
+
+```env
+# CORS Settings
+CORS_ORIGINS="*"                         # Comma-separated origins (use specific domains in production)
+CORS_METHODS="*"                         # Comma-separated HTTP methods or "*" for all
+CORS_HEADERS="*"                         # Comma-separated headers or "*" for all
+```
+
+!!! warning "CORS in Production"
+    Never use `"*"` for CORS_ORIGINS in production. Specify exact domains:
+    ```env
+    CORS_ORIGINS="https://yourapp.com,https://www.yourapp.com"
+    CORS_METHODS="GET,POST,PUT,DELETE,PATCH"
+    CORS_HEADERS="Authorization,Content-Type"
+    ```
+
 ### First Tier
 
 ```env

docs/getting-started/configuration.md

@@ -172,6 +172,40 @@ ADMIN_PASSWORD="secure_admin_password"
 - `ADMIN_USERNAME`: Username for admin login
 - `ADMIN_PASSWORD`: Initial password (change after first login)
 
+### CORS Configuration
+
+Cross-Origin Resource Sharing (CORS) settings for frontend integration:
+
+```env
+# ------------- CORS -------------
+CORS_ORIGINS="*"
+CORS_METHODS="*"
+CORS_HEADERS="*"
+```
+
+**Variables Explained:**
+
+- `CORS_ORIGINS`: Comma-separated list of allowed origins (e.g., `"https://app.com,https://www.app.com"`)
+- `CORS_METHODS`: Comma-separated list of allowed HTTP methods (e.g., `"GET,POST,PUT,DELETE"`)
+- `CORS_HEADERS`: Comma-separated list of allowed headers (e.g., `"Authorization,Content-Type"`)
+
+**Environment-Specific Values:**
+
+```env
+# Development - Allow all origins
+CORS_ORIGINS="*"
+CORS_METHODS="*"
+CORS_HEADERS="*"
+
+# Production - Specific domains only
+CORS_ORIGINS="https://yourapp.com,https://www.yourapp.com"
+CORS_METHODS="GET,POST,PUT,DELETE,PATCH"
+CORS_HEADERS="Authorization,Content-Type,X-Requested-With"
+```
+
+!!! danger "Security Warning"
+    Never use wildcard (`*`) for `CORS_ORIGINS` in production environments. Always specify exact allowed domains to prevent unauthorized cross-origin requests.
+
 ### User Tiers
 
 Initial tier configuration:

docs/user-guide/configuration/environment-variables.md

@@ -0,0 +1,67 @@
+# ============================================================================
+# WARNING: EXAMPLE CONFIGURATION - DO NOT USE IN PRODUCTION AS-IS
+# ============================================================================
+# This file contains example values for development/testing purposes only.
+#
+# SECURITY CRITICAL: Before deploying to production, you MUST:
+#   1. Copy this file to src/.env
+#   2. Generate a new SECRET_KEY using: openssl rand -hex 32
+#   3. Change all passwords (POSTGRES_PASSWORD, ADMIN_PASSWORD, etc.)
+#   4. Update all sensitive configuration values
+#
+# Using these example values in production is a SECURITY RISK.
+# ============================================================================
+
+# ------------- app settings -------------
+APP_NAME="My Project"
+APP_DESCRIPTION="My Project Description"
+APP_VERSION="0.1"
+CONTACT_NAME="Me"
+CONTACT_EMAIL="[email protected]"
+LICENSE_NAME="MIT"
+
+# ------------- database ------------- 
+POSTGRES_USER="postgres"
+POSTGRES_PASSWORD=1234
+POSTGRES_SERVER="db"
+POSTGRES_PORT=5432
+POSTGRES_DB="postgres"
+POSTGRES_ASYNC_PREFIX="postgresql+asyncpg://"
+
+# ------------- crypt -------------
+SECRET_KEY=953843cd400d99a039698e7feb46ca1b3e33c44fee2c24c6d88cf0f0b290fb61
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=60
+
+# ------------- admin -------------
+ADMIN_NAME="admin"
+ADMIN_EMAIL="[email protected]"
+ADMIN_USERNAME="admin"
+ADMIN_PASSWORD="Str1ngst!"
+
+# ------------- redis cache -------------
+REDIS_CACHE_HOST="redis"
+REDIS_CACHE_PORT=6379
+
+# ------------- redis queue -------------
+REDIS_QUEUE_HOST="redis"
+REDIS_QUEUE_PORT=6379
+
+# ------------- redis rate limit -------------
+REDIS_RATE_LIMIT_HOST="redis"
+REDIS_RATE_LIMIT_PORT=6379
+
+# ------------- client side cache -------------
+CLIENT_CACHE_MAX_AGE=60
+
+# ------------- test -------------
+TEST_NAME="Tester User"
+TEST_EMAIL="[email protected]"
+TEST_USERNAME="testeruser"
+TEST_PASSWORD="Str1ngT3st!"
+
+# ------------- environment -------------
+ENVIRONMENT="staging"
+
+# ------------- first tier -------------
+TIER_NAME="free"

scripts/gunicorn_managing_uvicorn_workers/.env.example

@@ -0,0 +1,27 @@
+# --------- requirements ---------
+
+FROM python:3.11 as requirements-stage
+
+WORKDIR /tmp
+
+RUN pip install poetry
+
+COPY ./pyproject.toml ./poetry.lock* /tmp/
+
+RUN poetry export -f requirements.txt --output requirements.txt --without-hashes
+
+
+# --------- final image build ---------
+FROM python:3.11
+
+WORKDIR /code
+
+COPY --from=requirements-stage /tmp/requirements.txt /code/requirements.txt
+
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+COPY ./src/app /code/app
+
+# -------- replace with comment to run with gunicorn --------
+# CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
+CMD ["gunicorn", "app.main:app", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000"]

scripts/gunicorn_managing_uvicorn_workers/Dockerfile

@@ -0,0 +1,112 @@
+services:
+  web:
+    build: 
+      context: .
+      dockerfile: Dockerfile
+    # -------- Both of the following commands should be commented to run with nginx --------
+
+    # -------- replace with comment to run with gunicorn or just uvicorn --------
+    # command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+    command: gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
+    env_file:
+      - ./src/.env
+    # -------- replace with expose if you are using nginx --------
+    ports:
+       - "8000:8000"
+    # expose:
+    #    - "8000"
+    depends_on:
+      - db
+      - redis
+    volumes:
+      - ./src/app:/code/app
+      - ./src/.env:/code/.env
+
+  worker:
+    build: 
+      context: .
+      dockerfile: Dockerfile
+    command: arq app.core.worker.settings.WorkerSettings
+    env_file:
+      - ./src/.env
+    depends_on:
+      - db
+      - redis
+    volumes:
+      - ./src/app:/code/app
+      - ./src/.env:/code/.env
+
+  db:
+    image: postgres:13
+    env_file:
+      - ./src/.env
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    expose:
+      - "5432"
+
+  redis:
+    image: redis:alpine
+    volumes:
+      - redis-data:/data
+    expose:
+      - "6379"
+
+  #-------- uncomment to run with nginx --------
+  # nginx:
+  #   image: nginx:latest
+  #   ports:
+  #     - "80:80"
+  #   volumes:
+  #     - ./default.conf:/etc/nginx/conf.d/default.conf
+  #   depends_on:
+  #     - web
+
+  #-------- uncomment to create first superuser --------
+  create_superuser:
+    build: 
+      context: .
+      dockerfile: Dockerfile
+    env_file:
+      - ./src/.env
+    depends_on:
+      - db
+      - web
+    command: python -m src.scripts.create_first_superuser
+    volumes:
+      - ./src:/code/src
+
+  #-------- uncomment to run tests --------
+  # pytest:
+  #   build: 
+  #     context: .
+  #     dockerfile: Dockerfile 
+  #   env_file:
+  #     - ./src/.env
+  #   depends_on:
+  #     - db
+  #     - create_superuser
+  #     - redis
+  #   command: python -m pytest ./tests
+  #   volumes:
+  #     - .:/code
+
+  #-------- uncomment to create first tier --------
+  # create_tier:
+  #   build: 
+  #     context: .
+  #     dockerfile: Dockerfile
+  #   env_file:
+  #     - ./src/.env
+  #   depends_on:
+  #     - create_superuser
+  #     - db
+  #     - web
+  #   command: python -m src.scripts.create_first_tier
+  #   volumes:
+  #     - ./src:/code/src
+
+volumes:
+  postgres-data:
+  redis-data:
+ 

scripts/gunicorn_managing_uvicorn_workers/docker-compose.yml

@@ -0,0 +1,72 @@
+# ============================================================================
+# WARNING: EXAMPLE CONFIGURATION - DO NOT USE IN PRODUCTION AS-IS
+# ============================================================================
+# This file contains example values for development/testing purposes only.
+#
+# SECURITY CRITICAL: Before deploying to production, you MUST:
+#   1. Copy this file to src/.env
+#   2. Generate a new SECRET_KEY using: openssl rand -hex 32
+#   3. Change all passwords (POSTGRES_PASSWORD, ADMIN_PASSWORD, etc.)
+#   4. Update all sensitive configuration values
+#
+# Using these example values in production is a SECURITY RISK.
+# ============================================================================
+
+# ------------- app settings -------------
+APP_NAME="My Project"
+APP_DESCRIPTION="My Project Description"
+APP_VERSION="0.1"
+CONTACT_NAME="Me"
+CONTACT_EMAIL="[email protected]"
+LICENSE_NAME="MIT"
+
+# ------------- database ------------- 
+POSTGRES_USER="postgres"
+POSTGRES_PASSWORD=1234
+POSTGRES_SERVER="db"
+POSTGRES_PORT=5432
+POSTGRES_DB="postgres"
+POSTGRES_ASYNC_PREFIX="postgresql+asyncpg://"
+
+# ------------- crypt -------------
+SECRET_KEY=de2132a4a3a029d6a93a2aefcb519f0219990f92ca258a7c5ed938a444dbe1c8
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=60
+
+# ------------- admin -------------
+ADMIN_NAME="admin"
+ADMIN_EMAIL="[email protected]"
+ADMIN_USERNAME="admin"
+ADMIN_PASSWORD="Str1ngst!"
+
+# ------------- redis cache -------------
+REDIS_CACHE_HOST="redis"
+REDIS_CACHE_PORT=6379
+
+# ------------- redis queue -------------
+REDIS_QUEUE_HOST="redis"
+REDIS_QUEUE_PORT=6379
+
+# ------------- redis rate limit -------------
+REDIS_RATE_LIMIT_HOST="redis"
+REDIS_RATE_LIMIT_PORT=6379
+
+# ------------- client side cache -------------
+CLIENT_CACHE_MAX_AGE=60
+
+# ------------- CORS -------------
+CORS_ORIGINS="*"
+CORS_METHODS="*"
+CORS_HEADERS="*"
+
+# ------------- test -------------
+TEST_NAME="Tester User"
+TEST_EMAIL="[email protected]"
+TEST_USERNAME="testeruser"
+TEST_PASSWORD="Str1ngT3st!"
+
+# ------------- environment -------------
+ENVIRONMENT="local"
+
+# ------------- first tier -------------
+TIER_NAME="free"

scripts/local_with_uvicorn/.env.example

@@ -0,0 +1,44 @@
+# --------- Builder Stage ---------
+FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim AS builder
+
+# Set environment variables for uv
+ENV UV_COMPILE_BYTECODE=1
+ENV UV_LINK_MODE=copy
+
+WORKDIR /app
+
+# Install dependencies first (for better layer caching)
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --locked --no-install-project
+
+# Copy the project source code
+COPY . /app
+
+# Install the project in non-editable mode
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-editable
+
+# --------- Final Stage ---------
+FROM python:3.11-slim-bookworm
+
+# Create a non-root user for security
+RUN groupadd --gid 1000 app \
+    && useradd --uid 1000 --gid app --shell /bin/bash --create-home app
+
+# Copy the virtual environment from the builder stage
+COPY --from=builder --chown=app:app /app/.venv /app/.venv
+
+# Ensure the virtual environment is in the PATH
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Switch to the non-root user
+USER app
+
+# Set the working directory
+WORKDIR /code
+
+# -------- replace with comment to run with gunicorn --------
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
+# CMD ["gunicorn", "app.main:app", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000"]