Merge pull request #218 from carlosplanchon/new_readme

New README.md & installation scripts now live in the scripts folder.

Author: igorbenav

.gitignore

@@ -135,3 +135,14 @@ cython_debug/
 .idea
 
 .vscode/
+
+# Config files:
+src/.env
+
+# Ignore root files:
+/Dockerfile
+/docker-compose.yml
+
+# Don't ignore files inside of script folder:
+!scripts/*
+

README.md

@@ -31,19 +31,35 @@ Install these tools on your system:
    cd fastapi-boilerplate
    ```
 
-1. **Set up environment**:
+1. **Quick setup** (recommended):
 
    ```bash
-   cp src/.env.example src/.env
-   # Edit src/.env with your configuration
+   # Interactive setup - choose your deployment type
+   ./setup.py
+   
+   # Or specify directly: ./setup.py local, ./setup.py staging, ./setup.py production
    ```
 
+   This automatically copies the correct `Dockerfile`, `docker-compose.yml`, and `.env` files for your chosen deployment scenario.
+
 1. **Start services**:
 
    ```bash
    docker compose up -d
    ```
 
+#### Manual Setup Alternative
+
+If you prefer to set up manually:
+
+```bash
+# Copy configuration files for local development
+cp scripts/local_with_uvicorn/Dockerfile Dockerfile
+cp scripts/local_with_uvicorn/docker-compose.yml docker-compose.yml  
+cp scripts/local_with_uvicorn/.env.example src/.env
+# Edit src/.env with your configuration if needed
+```
+
 1. **Verify installation**:
 
    ```bash

docker-compose.test.yml

@@ -2,6 +2,22 @@
 
 Learn how to configure and run the FastAPI Boilerplate using Docker Compose. The project includes a complete containerized setup with PostgreSQL, Redis, background workers, and optional services.
 
+## Quick Start
+
+The fastest way to get started is with the setup script:
+
+```bash
+./setup.py
+```
+
+This script helps you choose between three deployment configurations:
+
+- **Local development** (`./setup.py local`) - Uvicorn with auto-reload
+- **Staging** (`./setup.py staging`) - Gunicorn with workers  
+- **Production** (`./setup.py production`) - NGINX + Gunicorn
+
+Each option copies the appropriate `Dockerfile`, `docker-compose.yml`, and `.env.example` files from the `scripts/` folder.
+
 ## Docker Compose Architecture
 
 The boilerplate includes these core services:

docs/getting-started/installation.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"

docs/user-guide/configuration/docker-setup.md

@@ -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/.env.example

@@ -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/Dockerfile

@@ -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=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
+
+# ------------- test -------------
+TEST_NAME="Tester User"
+TEST_EMAIL="[email protected]"
+TEST_USERNAME="testeruser"
+TEST_PASSWORD="Str1ngT3st!"
+
+# ------------- environment -------------
+ENVIRONMENT="local"
+
+# ------------- first tier -------------
+TIER_NAME="free"