Deployment Guide

Everything you need to self-host ExMint — from a free Plaid sandbox account to a hardened production setup. Covers Docker, environment configuration, database migrations, and optional Plaid Production access.

Prerequisites

You will need the following before deploying ExMint:

Plaid Setup

ExMint uses Plaid to connect bank accounts. Plaid offers three tiers — choose the one that matches your use case.

Sandbox (free, simulated data)

The Sandbox tier is free, requires no approval, and uses simulated financial data. It is the recommended starting point for all new deployments.

PLAID_ENV=sandbox
PLAID_CLIENT_ID=your_client_id_here
PLAID_SECRET=your_sandbox_secret_here

Development (free, up to 100 real items)

The Development environment allows you to connect real bank accounts (up to 100 items) at no cost. It is suitable for personal use or testing with live data before going to Production.

PLAID_ENV=development
PLAID_SECRET=your_development_secret_here   # different from Sandbox secret

Production (paid, unlimited real items)

Production is required for deployments serving multiple users or connecting more than 100 real bank accounts. Plaid charges per connected item (bank account link).

PLAID_ENV=production
PLAID_SECRET=your_production_secret_here
PLAID_WEBHOOK_URL=https://yourdomain.com/plaid_webhook

Environment Variables

Copy .env.example to your target env file and fill in all values. ExMint uses different env files per environment: .env.dev, .env.stag, and .env.main.

Database Setup

Create a MySQL/MariaDB database and user, then run the Alembic migrations to set up the schema.

-- Create database and user
CREATE DATABASE exmint CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'exmint'@'%' IDENTIFIED BY 'your_strong_password';
GRANT ALL PRIVILEGES ON exmint.* TO 'exmint'@'%';
FLUSH PRIVILEGES;

Then run migrations via Docker:

docker-compose --env-file .env.dev -p exmint-dev \
  run --rm flask-app flask db upgrade

Docker Deployment

ExMint uses a single docker-compose.yml for all environments, controlled by the FLASK_ENV variable and the env file you pass in.

Local / Development

# Clone and configure
git clone https://github.com/manuelravila/ExMint.git
cd ExMint
cp .env.example .env.dev
# Edit .env.dev with your values

# Run migrations
docker-compose --env-file .env.dev -p exmint-dev \
  run --rm flask-app flask db upgrade

# Start
docker-compose --env-file .env.dev -p exmint-dev up -d --build

Open http://localhost:5000, register your first account, and connect a bank.

Staging

docker-compose --env-file .env.stag -p exmint-stag up -d --build

Production

# Apply any new migrations first
docker-compose --env-file .env.main -p exmint-prod \
  run --rm flask-app flask db upgrade

# Build and start
docker-compose --env-file .env.main -p exmint-prod up -d --build

Plaid Webhooks

Webhooks enable real-time transaction sync — new transactions appear automatically without a manual refresh. Without webhooks, users must sync manually.

To enable webhooks:

1. Ensure your ExMint deployment is accessible over HTTPS.
2. Set PLAID_WEBHOOK_URL=https://yourdomain.com/plaid_webhook in your env file.
3. Rebuild and restart the Docker container.
4. New bank connections will automatically register the webhook with Plaid. Existing connections need to be re-linked to pick up the new webhook URL.

Database Migrations

ExMint uses Alembic (via Flask-Migrate) for schema migrations. Migration files live in migrations/versions/.

# Apply all pending migrations
flask db upgrade

# Generate a new migration after a model change
flask db migrate -m "describe your change"

# Roll back one step
flask db downgrade

Secrets Management

ExMint resolves secrets through a two-tier lookup in secrets_manager.py:

1. Environment variable — os.getenv('KEY'). This is the recommended approach for self-hosters.
2. Bitwarden Secrets Manager (BWS) — only used when BWS_ACCESS_TOKEN is set in the environment. This is the maintainer's production deployment method and is entirely optional.

Self-hosters only need plain env vars. Simply omit BWS_ACCESS_TOKEN from your env file.

Troubleshooting

Login redirect loop

Usually caused by SESSION_COOKIE_SECURE=True when running without TLS. Ensure FLASK_ENV=dev in your local env file, which disables secure cookies automatically.

Database connection refused

When the database is on the host machine and the app is in Docker, use DB_HOST=host.docker.internal. On Linux, host.docker.internal may not be available — pass --add-host=host.docker.internal:host-gateway to Docker or use your host's LAN IP instead.

Plaid Link not opening

Ensure PLAID_CLIENT_ID and PLAID_SECRET are set correctly for the right environment (PLAID_ENV). Check the browser console for a 500 error on /api/create_link_token. If PLAID_WEBHOOK_URL is set but not a valid HTTPS URL, remove it until your webhook endpoint is ready.

Migrations fail with permission denied

Run migrations with explicit Python invocation inside Docker:

docker-compose --env-file .env.dev -p exmint-dev \
  run --rm flask-app python -m flask db upgrade

Transactions not syncing automatically

Real-time sync requires Plaid webhooks. Ensure PLAID_WEBHOOK_URL is set, your server is reachable over HTTPS, and the container was rebuilt after adding the env var. You can always trigger a manual sync from the dashboard.