Skip to main content

​
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)
  • Check Python Version
  • Install Poetry
python --version
# Should output Python 3.8 or higher

​
Install Tasteful

For new projects, use the Tasteful CLI to generate a project template: 
# 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: 
# 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: 
# 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: 
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)
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: 
# .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: 
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()
For comprehensive configuration patterns, see the Configuration Management Guide.

​
Database Setup

​
SQLAlchemy Integration

For database integration, install SQLAlchemy support: 
# 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: 
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: 
# Initialize Alembic
alembic init migrations

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

# Apply migrations
alembic upgrade head

​
Docker Setup

​
Dockerfile

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

# 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: 
// .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

Quick Start Tutorial

Build your first Tasteful application

Core Concepts

Learn about flavors, services, and architecture

Built-in Flavors

Explore ready-to-use functionality

​
Troubleshooting

​
Common Issues

Ensure you’ve installed Tasteful in your current Python environment:
pip list | grep tasteful
# Should show tasteful-core and any extensions
Change the port in your main.py or kill the process using port 8000:
# Find process using port 8000
lsof -i :8000

# Kill process
kill -9 <PID>
Verify your database is running and the connection string is correct:
# For PostgreSQL
psql -h localhost -U user -d myapp

# For SQLite
sqlite3 test.db ".tables"
Need help? Check our GitHub issues or browse the community discussions.
⌘I