initial commit

2025-10-19 22:09:35 +03:00
commit 6d593b4554
114 changed files with 23622 additions and 0 deletions
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@ -0,0 +1,366 @@
+# Installation Guide
+
+This guide covers different ways to install and set up the FastAPI Boilerplate depending on your needs and environment.
+
+## System Requirements
+
+Before you begin, ensure your system meets these requirements:
+
+- **Python**: 3.11 or higher
+- **Operating System**: Linux, macOS, or Windows (with WSL2 recommended)
+- **Memory**: Minimum 4GB RAM (8GB recommended)
+- **Disk Space**: At least 2GB free space
+
+## Method 1: Docker Compose (Recommended)
+
+Docker Compose is the easiest way to get started. It handles all dependencies and services automatically.
+
+### Prerequisites
+
+Install these tools on your system:
+
+- [Docker](https://docs.docker.com/get-docker/) (version 20.10+)
+- [Docker Compose](https://docs.docker.com/compose/install/) (version 1.29+)
+
+### Installation Steps
+
+1. **Get the template**:
+   ```bash
+   git clone https://github.com/benavlabs/fastapi-boilerplate
+   cd fastapi-boilerplate
+   ```
+
+2. **Set up environment**:
+   ```bash
+   cp src/.env.example src/.env
+   # Edit src/.env with your configuration
+   ```
+
+3. **Start services**:
+   ```bash
+   docker compose up -d
+   ```
+
+4. **Verify installation**:
+   ```bash
+   curl http://localhost:8000/docs
+   ```
+
+### What Gets Installed
+
+Docker Compose sets up these services:
+
+- **Web server** (FastAPI + Uvicorn) on port 8000
+- **PostgreSQL** database on port 5432 (internal)
+- **Redis** server on port 6379 (internal)
+- **ARQ Worker** for background tasks
+- **NGINX** (optional, for production)
+
+## Method 2: Manual Installation
+
+For more control or development purposes, you can install everything manually.
+
+### Prerequisites
+
+1. **Install Python 3.11+**:
+   ```bash
+   # On Ubuntu/Debian
+   sudo apt update
+   sudo apt install python3.11 python3.11-pip
+   
+   # On macOS (with Homebrew)
+   brew install python@3.11
+   
+   # On Windows
+   # Download from python.org
+   ```
+
+2. **Install uv** (Python package manager):
+   ```bash
+   pip install uv
+   ```
+
+3. **Install PostgreSQL**:
+   ```bash
+   # On Ubuntu/Debian
+   sudo apt install postgresql postgresql-contrib
+   
+   # On macOS
+   brew install postgresql
+   
+   # On Windows
+   # Download from postgresql.org
+   ```
+
+4. **Install Redis**:
+   ```bash
+   # On Ubuntu/Debian
+   sudo apt install redis-server
+   
+   # On macOS
+   brew install redis
+   
+   # On Windows
+   # Download from redis.io
+   ```
+
+### Installation Steps
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/benavlabs/fastapi-boilerplate
+   cd fastapi-boilerplate
+   ```
+
+2. **Install Python dependencies**:
+   ```bash
+   uv sync
+   ```
+
+3. **Set up environment variables**:
+   ```bash
+   cp src/.env.example src/.env
+   # Edit src/.env with your local database/Redis settings
+   ```
+
+4. **Set up PostgreSQL**:
+   ```bash
+   # Create database and user
+   sudo -u postgres psql
+   CREATE DATABASE myapp;
+   CREATE USER myuser WITH PASSWORD 'mypassword';
+   GRANT ALL PRIVILEGES ON DATABASE myapp TO myuser;
+   \q
+   ```
+
+5. **Run database migrations**:
+   ```bash
+   cd src
+   uv run alembic upgrade head
+   ```
+
+6. **Create admin user**:
+   ```bash
+   uv run python -m src.scripts.create_first_superuser
+   ```
+
+7. **Start the application**:
+   ```bash
+   uv run uvicorn src.app.main:app --reload --host 0.0.0.0 --port 8000
+   ```
+
+8. **Start the worker** (in another terminal):
+   ```bash
+   uv run arq src.app.core.worker.settings.WorkerSettings
+   ```
+
+## Method 3: Development Setup
+
+For contributors and advanced users who want to modify the boilerplate.
+
+### Additional Prerequisites
+
+- **Git** for version control
+- **Pre-commit** for code quality
+
+### Installation Steps
+
+1. **Fork and clone**:
+   ```bash
+   # Fork the repository on GitHub first
+   git clone https://github.com/yourusername/fastapi-boilerplate
+   cd fastapi-boilerplate
+   ```
+
+2. **Install development dependencies**:
+   ```bash
+   uv sync --group dev
+   ```
+
+3. **Set up pre-commit hooks**:
+   ```bash
+   uv run pre-commit install
+   ```
+
+4. **Set up development environment**:
+   ```bash
+   cp src/.env.example src/.env
+   # Configure for development
+   ```
+
+5. **Run tests to verify setup**:
+   ```bash
+   uv run pytest
+   ```
+
+## Docker Services Breakdown
+
+Understanding what each Docker service does:
+
+### Web Service
+```yaml
+web:
+  build: .
+  ports:
+    - "8000:8000"
+  depends_on:
+    - db
+    - redis
+```
+- Runs the FastAPI application
+- Handles HTTP requests
+- Auto-reloads on code changes (development)
+
+### Database Service
+```yaml
+db:
+  image: postgres:13
+  environment:
+    POSTGRES_DB: myapp
+    POSTGRES_USER: postgres
+    POSTGRES_PASSWORD: changethis
+```
+- PostgreSQL database server
+- Persistent data storage
+- Automatic initialization
+
+### Redis Service
+```yaml
+redis:
+  image: redis:alpine
+  command: redis-server --appendonly yes
+```
+- In-memory data store
+- Used for caching and job queues
+- Persistent storage with AOF
+
+### Worker Service
+```yaml
+worker:
+  build: .
+  command: arq src.app.core.worker.settings.WorkerSettings
+  depends_on:
+    - redis
+```
+- Background task processor
+- Handles async jobs
+- Scales independently
+
+## Configuration
+
+### Environment Variables
+
+The application uses environment variables for configuration. Key variables:
+
+```env
+# Database
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=changethis
+POSTGRES_SERVER=localhost  # or "db" for Docker
+POSTGRES_PORT=5432
+POSTGRES_DB=myapp
+
+# Redis
+REDIS_CACHE_HOST=localhost  # or "redis" for Docker
+REDIS_CACHE_PORT=6379
+
+# Security
+SECRET_KEY=your-secret-key-here
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+```
+
+### Database Connection
+
+For manual installation, update your database settings:
+
+```env
+# Local PostgreSQL
+POSTGRES_SERVER=localhost
+POSTGRES_PORT=5432
+
+# Docker PostgreSQL
+POSTGRES_SERVER=db
+POSTGRES_PORT=5432
+```
+
+## Verification
+
+After installation, verify everything works:
+
+1. **API Documentation**: http://localhost:8000/docs
+2. **Health Check**: http://localhost:8000/api/v1/health
+3. **Database Connection**: Check logs for successful connection
+4. **Redis Connection**: Test caching functionality
+5. **Background Tasks**: Submit a test job
+
+## Troubleshooting
+
+### Common Issues
+
+**Port Already in Use**:
+```bash
+# Check what's using port 8000
+lsof -i :8000
+
+# Kill the process
+kill -9 <PID>
+```
+
+**Database Connection Error**:
+```bash
+# Check PostgreSQL status
+sudo systemctl status postgresql
+
+# Restart PostgreSQL
+sudo systemctl restart postgresql
+```
+
+**Redis Connection Error**:
+```bash
+# Check Redis status
+redis-cli ping
+
+# Start Redis
+redis-server
+```
+
+**Permission Errors**:
+```bash
+# Fix Docker permissions
+sudo usermod -aG docker $USER
+# Log out and back in
+```
+
+### Docker Issues
+
+**Clean Reset**:
+```bash
+# Stop all containers
+docker compose down
+
+# Remove volumes (⚠️ deletes data)
+docker compose down -v
+
+# Rebuild images
+docker compose build --no-cache
+
+# Start fresh
+docker compose up
+```
+
+## Next Steps
+
+After successful installation:
+
+1. **[Configuration Guide](configuration.md)** - Set up your environment
+2. **[First Run](first-run.md)** - Test your installation
+3. **[Project Structure](../user-guide/project-structure.md)** - Understand the codebase
+
+## Need Help?
+
+If you encounter issues:
+
+- Check the [GitHub Issues](https://github.com/benavlabs/fastapi-boilerplate/issues) for common problems
+- Search [existing issues](https://github.com/benavlabs/fastapi-boilerplate/issues)
+- Create a [new issue](https://github.com/benavlabs/fastapi-boilerplate/issues/new) with details