Cookbook Recipe Management Application

A Flask-based web application for managing recipes with ingredients, images, and unit conversions.

This repo is on Gitea!

I'm hosting this repo on my gitea instance. All commits to either remote and CI should sync between GitHub and Gitea.

A note on the README

Part of the README for this repo has been generated AI and modified, because I would prefer to focus on development over writing the README. It should still be okay.

Features

• Recipe management with ingredients and directions
• Image upload and storage (currently stored in filesystem with abstractions to be moved to bucket later)
• Unit conversions for recipe ingredients
• Ingredient density tracking for weight calculations

Contributing – Not just for devs!

Obviously, software development help would be great, but feature requests are really great too! At some point, I will be happy with this repo and need more feature requests to work on. Please create a discussion post or issue.

Requirements

• Python 3.10+
• Node.js 20+ (for SCSS compilation)
• pnpm package manager
• Docker & Docker Compose (optional, for containerized deployment)

Environment Variables

The application uses environment variables for configuration:

• DATABASE_URL: Database connection string (defaults to SQLite for local dev)
• SECRET_KEY: Flask secret key for session management and security

Installation

If you have PostgreSQL running locally and want to use it, you probably know how to set up Docker Compose. Skip to Use an existing PostgreSQL server

### 1. Clone the repository

```bash
git clone https://github.com/EReaso/cookbook.git
cd cookbook

2. Set up Python virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Python dependencies

pip install -r requirements.txt

For development (includes testing and linting tools):

pip install -r requirements-dev.txt

4. Install Node.js dependencies

pnpm install

5. Initialize the database

flask db upgrade

6. Build CSS assets

pnpm run build

Running the Application

Quick Start with Docker Compose (Recommended)

The easiest way to get started is with the quickstart script:

./scripts/quickstart.sh

This script will:

• Create a .env file with generated SECRET_KEY and POSTGRES_PASSWORD
• Create a protected external Docker volume for PostgreSQL data
• Provide you with the command to start the application

After running the script, start the application with this command:

docker compose --profile local up --build

The application will be available at http://localhost:5000 depending on your environment.

Manual Setup (Alternative):

If you prefer manual setup or the script doesn't work for your environment:

1. Set up environment variables:

cp .env.example .env
# Generate a secure SECRET_KEY and update .env
python -c "import secrets; print(secrets.token_hex(32))"

2. Create a protected database volume:

docker volume create cookbook_postgres_data

3. Start the application:

docker compose --profile local up --build

5. Stop the application:

docker compose down

To remove regular Compose volumes:

docker compose down -v

Data Persistence:

The application uses Docker volumes to persist data across container restarts:

• postgres_data: PostgreSQL database data
• instance_data: Flask instance directory, which includes uploaded image files stored in /app/instance/storage

postgres_data is configured as an external named volume (cookbook_postgres_data by default), so docker compose down -v does not remove it. This makes accidental DB deletion much harder.

To intentionally delete DB data, remove that volume explicitly:

docker volume rm cookbook_postgres_data

Use an existing PostgreSQL server

If you already run Postgres elsewhere, set DATABASE_URL in .env and start only the app service:

docker compose up --build web

Local Development Server

For local development without Docker:

python wsgi.py

The application will be available at http://localhost:5000

Production Server

Use gunicorn:

gunicorn wsgi:wsgi_app

Testing

Run all tests

pytest

Run tests with coverage

pytest --cov=app --cov-report=html

View coverage report by opening htmlcov/index.html in your browser.

Run specific test file

pytest tests/test_models.py

Run screenshot capture manually

To run the same screenshot generation step locally as CI:

python -m playwright install --with-deps chromium
python scripts/take_screenshots.py --config screenshots.yml --output-dir screenshots

Development

Code Style

This project uses Ruff for both linting and formatting:

• 4-space indentation
• Line length: 120 characters
• Import sorting via Ruff's isort-compatible rules

Code Quality Tools

Format code with Ruff:

ruff format .

Auto-fix lint issues:

ruff check --fix .

Lint code with Ruff:

ruff check .

Pre-commit Hooks

Install pre-commit hooks:

pre-commit install

Run hooks manually:

pre-commit run --all-files

Database Migrations

Create a new migration:

flask db migrate -m "Description of changes"

Apply migrations:

flask db upgrade

Rollback migration:

flask db downgrade

CI/CD

This project uses GitHub Actions for continuous integration:

• Tests: Runs on Python 3.12
• Linting: Checks code quality with Ruff
• Coverage: Uploads coverage reports to Codecov

Contributing (again)

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is open source and available under the AGPL 3.0 License.