Phase 2 build initial

hcfs-python/docs/installation.rst

@@ -0,0 +1,368 @@
+Installation
+============
+
+This guide covers installing HCFS and its SDK in various environments.
+
+Quick Installation
+------------------
+
+The fastest way to get started is to install the HCFS SDK from PyPI:
+
+.. code-block:: bash
+
+   pip install hcfs-sdk
+
+This installs the core SDK with basic dependencies.
+
+Full Installation
+-----------------
+
+For all features including WebSocket support, monitoring, and development tools:
+
+.. code-block:: bash
+
+   pip install hcfs-sdk[all]
+
+This includes optional dependencies for:
+
+* WebSocket streaming (``websockets``)
+* Advanced monitoring (``prometheus-client``, ``structlog``)
+* Development tools (``pytest``, ``black``, ``mypy``)
+
+Selective Installation
+----------------------
+
+You can install specific feature sets:
+
+.. code-block:: bash
+
+   # WebSocket streaming support
+   pip install hcfs-sdk[websocket]
+
+   # Monitoring and observability
+   pip install hcfs-sdk[monitoring]
+
+   # Development and testing
+   pip install hcfs-sdk[dev]
+
+   # Production deployment
+   pip install hcfs-sdk[production]
+
+Requirements
+------------
+
+System Requirements
+~~~~~~~~~~~~~~~~~~~
+
+* **Python**: 3.8 or higher
+* **Operating System**: Linux, macOS, or Windows
+* **Memory**: Minimum 512MB RAM, 2GB+ recommended for production
+* **Storage**: 100MB for installation, varies by usage
+
+Python Dependencies
+~~~~~~~~~~~~~~~~~~~
+
+Core dependencies (installed automatically):
+
+* ``httpx >= 0.25.0`` - HTTP client
+* ``pydantic >= 2.5.0`` - Data validation
+* ``requests >= 2.31.0`` - HTTP library
+
+Optional dependencies by feature:
+
+**WebSocket Support**:
+  * ``websockets >= 12.0``
+
+**Monitoring**:
+  * ``prometheus-client >= 0.19.0``
+  * ``structlog >= 23.2.0``
+
+**Development**:
+  * ``pytest >= 7.4.0``
+  * ``pytest-asyncio >= 0.21.0``
+  * ``black >= 23.9.0``
+  * ``mypy >= 1.6.0``
+
+Virtual Environment Setup
+--------------------------
+
+We strongly recommend using a virtual environment:
+
+Using venv
+~~~~~~~~~~
+
+.. code-block:: bash
+
+   # Create virtual environment
+   python -m venv hcfs-env
+
+   # Activate (Linux/macOS)
+   source hcfs-env/bin/activate
+
+   # Activate (Windows)
+   hcfs-env\\Scripts\\activate
+
+   # Install HCFS
+   pip install hcfs-sdk[all]
+
+Using conda
+~~~~~~~~~~~
+
+.. code-block:: bash
+
+   # Create conda environment
+   conda create -n hcfs-env python=3.9
+
+   # Activate environment
+   conda activate hcfs-env
+
+   # Install HCFS
+   pip install hcfs-sdk[all]
+
+Using Poetry
+~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   # Initialize project
+   poetry init
+
+   # Add HCFS dependency
+   poetry add hcfs-sdk[all]
+
+   # Install dependencies
+   poetry install
+
+Development Installation
+------------------------
+
+For development work on HCFS itself:
+
+.. code-block:: bash
+
+   # Clone the repository
+   git clone https://github.com/hcfs/hcfs.git
+   cd hcfs
+
+   # Create virtual environment
+   python -m venv venv
+   source venv/bin/activate  # or venv\\Scripts\\activate on Windows
+
+   # Install in development mode
+   pip install -e .[dev]
+
+   # Install pre-commit hooks
+   pre-commit install
+
+This installs HCFS in "editable" mode, so changes to the source code are immediately available.
+
+Docker Installation
+-------------------
+
+Run HCFS API server using Docker:
+
+.. code-block:: bash
+
+   # Run with default settings
+   docker run -p 8000:8000 hcfs/hcfs-api:latest
+
+   # Run with custom configuration
+   docker run -p 8000:8000 \
+     -e HCFS_API_KEY=your-api-key \
+     -e HCFS_DB_PATH=/data/hcfs.db \
+     -v /host/data:/data \
+     hcfs/hcfs-api:latest
+
+Docker Compose
+~~~~~~~~~~~~~~
+
+For a complete setup with database and monitoring:
+
+.. code-block:: yaml
+
+   version: '3.8'
+   services:
+     hcfs-api:
+       image: hcfs/hcfs-api:latest
+       ports:
+         - "8000:8000"
+       environment:
+         - HCFS_DB_PATH=/data/hcfs.db
+         - HCFS_API_ENABLE_METRICS=true
+       volumes:
+         - hcfs_data:/data
+       depends_on:
+         - redis
+
+     redis:
+       image: redis:7-alpine
+       ports:
+         - "6379:6379"
+
+   volumes:
+     hcfs_data:
+
+Verification
+------------
+
+Verify your installation:
+
+.. code-block:: python
+
+   import hcfs.sdk
+   print(f"HCFS SDK version: {hcfs.sdk.__version__}")
+
+   # Test basic functionality
+   from hcfs.sdk import HCFSClient, Context
+
+   # This will fail without a running server, but validates imports
+   try:
+       client = HCFSClient(base_url="http://localhost:8000", api_key="test")
+       print("SDK imported successfully!")
+   except Exception as e:
+       print(f"SDK imported (server not running): {e}")
+
+Command Line Interface
+----------------------
+
+HCFS includes a CLI for common operations:
+
+.. code-block:: bash
+
+   # Check version
+   hcfs --version
+
+   # Test API connection
+   hcfs health --url http://localhost:8000 --api-key your-key
+
+   # Run API server
+   hcfs serve --port 8000 --workers 4
+
+Configuration
+-------------
+
+The SDK can be configured through:
+
+1. **Environment Variables**:
+   
+   .. code-block:: bash
+
+      export HCFS_BASE_URL=https://api.hcfs.dev/v1
+      export HCFS_API_KEY=your-api-key
+      export HCFS_TIMEOUT=30.0
+
+2. **Configuration File** (``~/.hcfs/config.yaml``):
+
+   .. code-block:: yaml
+
+      base_url: https://api.hcfs.dev/v1
+      api_key: your-api-key
+      timeout: 30.0
+      cache:
+        enabled: true
+        max_size: 1000
+        ttl_seconds: 3600
+
+3. **Programmatic Configuration**:
+
+   .. code-block:: python
+
+      from hcfs.sdk import HCFSClient, ClientConfig
+
+      config = ClientConfig(
+          base_url="https://api.hcfs.dev/v1",
+          api_key="your-api-key",
+          timeout=30.0
+      )
+
+      client = HCFSClient(config=config)
+
+Troubleshooting
+---------------
+
+Common Issues
+~~~~~~~~~~~~~
+
+**ImportError: No module named 'hcfs'**
+   Ensure you've activated your virtual environment and installed the package:
+   
+   .. code-block:: bash
+
+      pip list | grep hcfs
+
+**Connection errors**
+   Verify the API server is running and accessible:
+   
+   .. code-block:: bash
+
+      curl -I http://localhost:8000/health
+
+**Permission errors on Windows**
+   Run command prompt as administrator or use:
+   
+   .. code-block:: bash
+
+      pip install --user hcfs-sdk
+
+**SSL certificate errors**
+   For development, you can disable SSL verification:
+   
+   .. code-block:: python
+
+      import httpx
+      client = HCFSClient(
+          base_url="https://localhost:8000",
+          api_key="test",
+          verify=False
+      )
+
+Getting Help
+~~~~~~~~~~~~
+
+If you encounter issues:
+
+1. Check this documentation
+2. Search `GitHub Issues <https://github.com/hcfs/hcfs/issues>`_
+3. Create a new issue with:
+   
+   * Python version (``python --version``)
+   * HCFS version (``pip show hcfs-sdk``)
+   * Operating system
+   * Full error message and traceback
+   * Minimal code example that reproduces the issue
+
+Updating
+--------
+
+Keep your installation up to date:
+
+.. code-block:: bash
+
+   # Update to latest version
+   pip install --upgrade hcfs-sdk
+
+   # Update with all dependencies
+   pip install --upgrade hcfs-sdk[all]
+
+   # Check current version
+   pip show hcfs-sdk
+
+For development installations:
+
+.. code-block:: bash
+
+   # Pull latest changes
+   git pull origin main
+
+   # Update dependencies
+   pip install -e .[dev] --upgrade
+
+Next Steps
+----------
+
+After installation:
+
+1. Read the :doc:`quickstart` guide
+2. Configure your :doc:`configuration` 
+3. Explore the :doc:`examples`
+4. Review the :doc:`sdk/overview` for advanced usage