Meutch

Meutch is a project that makes it easier for people to share items with each other. You can learn more about it, and actually share with people, at https://meutch.com/about.

This GitHub repo contains Meutch's source code. It's shared here for two reasons:

1. Transparency. Be reassured that indeed this is a project for the social good and it works as advertised.
2. Improvement. If you see a way to make Meutch better or more secure, please contribute it!

The theory of action is that Meutch is most effective when run as a single instance at https://meutch.com. Sam considered a decentralized, federated model but felt like the downsides outweighed the advantages. Ultimately, the most sharing would happen when everyone is on a single instance, and features are in place there (e.g., hidden circles) to make things safe for privacy-focused users.

This README is focused on developing and contributing to the codebase. But computer-savvy folks can deploy their own instances of Meutch for their communities; for more info one deploying Meutch in production, see DEPLOYMENT.md.

Development

Pre-requisite: install docker compose. Meutch runs as a Python flask app but there's a Postgres database users for local development that deploys with docker compose.

Start by cloning and pulling the repo to your machine. Set up a Python virtual environment in the venv/ directory.

Install the application and contributor dependencies into that environment:

source venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

Environment Setup

Copy the example environment file and customize it for your local setup:

cp .env.example .env

The default values in .env.example are configured for local development with the Docker PostgreSQL database. You can use them as-is or customize as needed. The file includes:

• Flask configuration (FLASK_ENV, FLASK_APP)
• Database connection string for development data (meutch_dev)
• A separate test database URL pattern (meutch_test) to isolate test runs from development data
• Storage backend configuration (defaults to local for development)
• Optional email and cloud storage settings (commented out by default)

Run the development environment, database migrations, and (optionally) the development data seeder:

• Start the local Postgres container (if you use the test compose file):

docker compose -f docker-compose.test.yml up -d

• Prepare, migrate, seed, and run in one command:

./dev-start.sh seed

The seed argument is optional. Without it ./dev-start.sh will prepare the environment and start the Flask server but will not run the data seeder.

• You can also run the steps manually (make sure you've set up your .env file first):

source venv/bin/activate
flask db upgrade
flask seed data --env development
flask run

Note: Flask automatically loads environment variables from the .env file (via python-dotenv), so you don't need to export them manually if you've created your .env file.

The dummy users seeded by the development data all have the same password. Login looks like: Username: user1@example.com Password: password123.

Testing Scheduled Emails (Digest + Loan Reminders)

Digest emails and overdue/due-soon loan notices run through the same daily CLI job:

flask check-loan-reminders

For normal behavior, run that command as-is. For local testing, the command supports overrides so you can run it repeatedly without waiting for the next day/week cadence:

# Force digest sends for daily/weekly users, ignoring cadence windows and last-sent checks
flask check-loan-reminders --force-digest

# Force loan reminder sends, bypassing sent/day/count guards
flask check-loan-reminders --force-loan-reminders

# Simulate loan reminder date rules for a specific day
flask check-loan-reminders --today 2026-03-14

# Simulate the digest scheduler evaluation timestamp in UTC
flask check-loan-reminders --digest-now "2026-03-16 12:00:00"

# Combine overrides for repeated end-to-end testing
flask check-loan-reminders --force-digest --force-loan-reminders --today 2026-03-14 --digest-now "2026-03-14 09:00:00"

Notes:

• Use overrides only in development/staging.
• --digest-now sets the scheduler's evaluation timestamp used for digest cadence/day-boundary checks (daily/weekly send windows).
• --today only affects loan reminder date logic (due soon / due today / overdue checks).
• You can combine both when testing both systems in one run.
• If EMAIL_ALLOWLIST is set, only allowlisted addresses receive emails.
• If Mailgun is not configured locally, this command still helps validate scheduling logic and CLI summaries.

Development Workflow

This repo uses pre-commit so contributors get the same checks locally and in CI.

Install the hooks once per clone:

./install-pre-commit-hook.sh

That script force-replaces any older custom git hook for this repo, so you do not need to manually uninstall the legacy hook first. What runs where:

• pre-commit on commit: fast checks only, against the files you are changing. That includes ruff linting, ruff format, pylint --errors-only, and basic YAML/whitespace checks.
• pre-push on push: the Alembic revision ID check and the unit test suite.
• GitHub Actions on pull requests: the same pre-commit checks run against the PR diff so contributors and CI stay aligned.

Useful commands:

pre-commit run --all-files
pre-commit run ruff-check --files path/to/file.py
pre-commit run pylint-errors-only --files path/to/file.py

This keeps local commit hooks fast on a legacy codebase while still enforcing linting on newly touched Python files. If you need to bypass the hook for a specific commit (use sparingly):

git commit --no-verify