> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tasteful.heka.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install and set up Tasteful for your development environment

# Installation

Get Tasteful up and running on your system in minutes.

## Prerequisites

Before installing Tasteful, ensure you have:

* **Python 3.8+** (Python 3.11+ recommended)
* **Poetry** (for dependency management) or **pip**
* **Git** (for cloning examples and contributing)

<Tabs>
  <Tab title="Check Python Version">
    ```bash theme={null}
    python --version
    # Should output Python 3.8 or higher
    ```
  </Tab>

  <Tab title="Install Poetry">
    ```bash theme={null}
    curl -sSL https://install.python-poetry.org | python3 -
    # Or via pip:
    pip install poetry
    ```
  </Tab>
</Tabs>

## Install Tasteful

### Using Poetry (Recommended)

For new projects, use the Tasteful CLI to generate a project template:

```bash theme={null}
# Install the CLI tool
pip install tasteful-cli

# Create a new project
tasteful new my-project

# Navigate to your project
cd my-project

# Install dependencies
poetry install
```

### Using pip

For existing projects or minimal installations:

```bash theme={null}
# Core framework
pip install tasteful-core

# With built-in flavors (recommended)
pip install tasteful-core[flavors]

# Development dependencies
pip install tasteful-core[dev]
```

### Development Installation

To contribute to Tasteful or work with the latest features:

```bash theme={null}
# Clone the repository
git clone https://github.com/heka-ai/tasteful.git
cd tasteful

# Install in development mode
poetry install

# Or with pip
pip install -e .
```

## Verify Installation

Create a simple test application to verify everything works:

<CodeGroup>
  ```python main.py theme={null}
  from tasteful import TastefulApp
  from tasteful.flavors import IdentityFlavor

  app = TastefulApp(
      title="Test Application",
      version="1.0.0",
      flavors=[IdentityFlavor],
      authentication_backends=[]
  )

  if __name__ == "__main__":
      import uvicorn
      uvicorn.run(app.app, host="0.0.0.0", port=8000)
  ```

  ```bash Terminal theme={null}
  python main.py
  ```
</CodeGroup>

Visit `http://localhost:8000/docs` to see the automatic API documentation, or `http://localhost:8000/identity/me` to test the identity endpoint.

## Project Structure

A typical Tasteful project structure:

```
my-project/
├── pyproject.toml          # Poetry configuration
├── main.py                 # Application entry point
├── config/
│   ├── __init__.py
│   └── settings.py         # Application configuration
├── flavors/
│   ├── __init__.py
│   ├── user/
│   │   ├── __init__.py
│   │   ├── flavor.py       # User flavor definition
│   │   ├── services.py     # Business logic
│   │   └── models.py       # Data models
│   └── order/
│       ├── __init__.py
│       ├── flavor.py
│       └── services.py
├── tests/
│   ├── __init__.py
│   ├── test_user.py
│   └── test_order.py
└── README.md
```

## Configuration

### Environment Variables

Configure your application using environment variables:

```bash theme={null}
# .env file
DATABASE_URL=postgresql://user:pass@localhost/mydb
REDIS_URL=redis://localhost:6379
SECRET_KEY=your-secret-key-here
DEBUG=true
ACTIVE_FLAVORS=user,order,payment
```

### Configuration File

Create a `config/settings.py` file using Tasteful's BaseConfig:

```python theme={null}
from tasteful.base_flavor import BaseConfig
from pydantic import Field

class AppConfig(BaseConfig):
    """Application configuration with automatic environment variable loading."""
    
    database_url: str = "sqlite:///./test.db"
    redis_url: str = "redis://localhost:6379"
    secret_key: str = Field(default="change-me-in-production", min_length=32)
    debug: bool = False
    active_flavors: str = "identity,user"

# Configuration is automatically loaded from environment variables
# and .env files thanks to BaseConfig
settings = AppConfig()
```

<Note>
  For comprehensive configuration patterns, see the [Configuration Management Guide](/guides/configuration-management).
</Note>

## Database Setup

### SQLAlchemy Integration

For database integration, install SQLAlchemy support:

```bash theme={null}
# With PostgreSQL
pip install tasteful-core[postgres]

# With MySQL
pip install tasteful-core[mysql]

# With SQLite (included)
pip install tasteful-core[sqlite]
```

Example database configuration with BaseConfig:

```python theme={null}
from tasteful.base_flavor import BaseConfig
from tasteful.repositories import BaseRepository
from pydantic import Field

class DatabaseConfig(BaseConfig):
    """Database configuration."""
    
    database_url: str = Field(
        default="sqlite:///./app.db",
        description="Database connection URL"
    )
    echo: bool = Field(
        default=False,
        description="Enable SQL query logging"
    )

class UserRepository(BaseRepository):
    def __init__(self, config: DatabaseConfig):
        super().__init__(
            database_url=config.database_url,
            echo=config.echo
        )
```

### Migrations with Alembic

Set up database migrations:

```bash theme={null}
# Initialize Alembic
alembic init migrations

# Create a migration
alembic revision --autogenerate -m "Create user table"

# Apply migrations
alembic upgrade head
```

## Docker Setup

### Dockerfile

```dockerfile theme={null}
FROM python:3.11-slim

WORKDIR /app

# Install Poetry
RUN pip install poetry

# Copy dependency files
COPY pyproject.toml poetry.lock ./

# Install dependencies
RUN poetry config virtualenvs.create false \
    && poetry install --no-dev

# Copy application code
COPY . .

# Expose port
EXPOSE 8000

# Run application
CMD ["python", "main.py"]
```

### Docker Compose

```yaml theme={null}
# docker-compose.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis

  db:
    image: postgres:13
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:6-alpine

volumes:
  postgres_data:
```

## IDE Setup

### VS Code

Recommended VS Code extensions:

```json theme={null}
// .vscode/extensions.json
{
  "recommendations": [
    "ms-python.python",
    "ms-python.pylint",
    "ms-python.black-formatter",
    "charliermarsh.ruff",
    "ms-python.mypy-type-checker"
  ]
}
```

### PyCharm

1. Open the project directory
2. Configure Poetry interpreter: **Settings > Project > Python Interpreter > Add > Poetry Environment**
3. Enable type checking: **Settings > Editor > Inspections > Python > Type checker**

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start Tutorial" icon="play" href="/quickstart">
    Build your first Tasteful application
  </Card>

  <Card title="Core Concepts" icon="book" href="/concepts/flavors">
    Learn about flavors, services, and architecture
  </Card>

  <Card title="Built-in Flavors" icon="puzzle-piece" href="/flavors/health">
    Explore ready-to-use functionality
  </Card>
</CardGroup>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="ImportError: No module named 'tasteful'">
    Ensure you've installed Tasteful in your current Python environment:

    ```bash theme={null}
    pip list | grep tasteful
    # Should show tasteful-core and any extensions
    ```
  </Accordion>

  <Accordion title="Port already in use">
    Change the port in your main.py or kill the process using port 8000:

    ```bash theme={null}
    # Find process using port 8000
    lsof -i :8000

    # Kill process
    kill -9 <PID>
    ```
  </Accordion>

  <Accordion title="Database connection errors">
    Verify your database is running and the connection string is correct:

    ```bash theme={null}
    # For PostgreSQL
    psql -h localhost -U user -d myapp

    # For SQLite
    sqlite3 test.db ".tables"
    ```
  </Accordion>
</AccordionGroup>

Need help? Check our [GitHub issues](https://github.com/heka-ai/tasteful/issues) or browse the [community discussions](https://github.com/heka-ai/tasteful/discussions).