368 lines
7.2 KiB
ReStructuredText
368 lines
7.2 KiB
ReStructuredText
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 |