Cookbook Recipe Management Application

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

A note on the README:

Part of the README for this repo has been generated by 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 fix. 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

1. Clone the repository

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
• Set up Docker secrets for Postgres password (if Swarm mode is active)
• In non-Swarm mode, the password from .env will be used
• Provide you with the command to start the application

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

docker-compose 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. Set up the password secret file:

# Create the password file from the example (default password is cookbook_dev_password)
mkdir -p .secrets
echo "cookbook_dev_password" > .secrets/postgres_password
chmod 600 .secrets/postgres_password

# Or use a custom secure password
echo "your_secure_password" > .secrets/postgres_password
chmod 600 .secrets/postgres_password

The .secrets/postgres_password file is used for Docker Compose secrets and is ignored by git. File permissions are set to 600 to restrict access to the owner only.

3. Start the application:

docker-compose up --build

5. Stop the application:

docker-compose down

To remove volumes (including database data and uploaded images):

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

These volumes ensure that your recipes, ingredients, and uploaded images are preserved when you stop and restart the containers. Only running docker-compose down -v will remove these volumes and delete the data.

About Docker Secrets:

This application uses file-based Docker secrets for enhanced security. The Postgres password is stored in .secrets/postgres_password file, which is shared with containers via Docker secrets mechanism. This file is excluded from version control via .gitignore to prevent accidentally committing secrets to the repository.

The password file approach works with both:

• Regular Docker Compose mode: Uses file-based secrets (default)
• Docker Swarm mode: Also compatible with file-based secrets

See .secrets/POSTGRES_PASSWORD.example for the example secret format.

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.