futurefin-run-and-operate

Deploy, upgrade, back up, and operate production FutureFin Docker Compose installations.

1|Updated May 2, 2026
One-click install
npx skills add https://github.com/maxlainz/FutureFin --skill futurefin-run-and-operate-maxlainz
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: futurefin-run-and-operate
Source: https://github.com/maxlainz/FutureFin/tree/main/.claude/skills/futurefin-run-and-operate
Command: npx skills add https://github.com/maxlainz/FutureFin --skill futurefin-run-and-operate-maxlainz

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Running a self-hosted FutureFin instance in production involves risky operations—upgrades that trigger database migrations, rollbacks constrained by forward-only migrations, and backups that must exist before anything touches the schema. This Skill provides the operational runbook so these tasks are done in the correct order without data loss. ## Core Features & Use Cases - Deploy and Upgrade: Deploy from zero with a single all-in-one Docker Compose container (embedded PostgreSQL since 3.0.0), pin image tags via FUTUREFIN_TAG, and migrate a legacy 2.x two-container stack. - Backup and Restore: Take and restore backups using automatic pre-migration dumps, the pg_dump scripts, and the per-user encrypted .ffbackup format. - Day-2 Operations: Read startup log milestones, distinguish health vs readiness probes (/v1/health vs /v1/ready), perform ordered shutdowns, and operate the Home Assistant add-on channel. - Use Case: Your FutureFin container reports unhealthy after pulling a new image. Use this Skill to read the entrypoint log milestones, determine whether the one-time collation reindex is still running, and verify the pre-migration backup was written before deciding to wait or roll back. ## Quick Start Ask the AI to walk you through upgrading your FutureFin Docker Compose deployment from version 2.x to 3.x without losing the existing pgdata volume.

Frequently Asked Questions about futurefin-run-and-operate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I upgrade FutureFin with Docker Compose?▼

Pin the new version in .env with FUTUREFIN_TAG, then run docker compose pull && docker compose up -d. New migrations run automatically on first start after the entrypoint writes a pre-migration backup, and /v1/health confirms the new version.

How do I migrate FutureFin from 2.x two containers to 3.x?▼

Replace docker-compose.yml with the 3.x file and run docker compose up -d --remove-orphans, keeping the existing pgdata volume. The first start adopts ownership, reindexes for the musl-to-glibc collation change, and writes a pre-migration backup.

Can I roll back FutureFin to an older version?▼

Rollback is only safe if the database has no migrations beyond what the older binary ships, since migrations roll forward only. Compare applied versions in _sqlx_migrations against the target tag's migrations directory before downgrading.

Why is my FutureFin container unhealthy after an upgrade?▼

During a 2.x to 3.x upgrade the one-time database reindex can exceed the 120-second healthcheck start_period, so the container reports unhealthy temporarily. Follow docker compose logs -f futurefin for the reindex milestones instead of watching docker ps.

What is the difference between /v1/health and /v1/ready?▼

/v1/health only confirms the process is up and returns the version, while /v1/ready runs SELECT 1 against the embedded PostgreSQL and returns 503 if the database is unreachable. Health OK with ready 503 means the API is fine but the database is not.

Does FutureFin support an external PostgreSQL database?▼

No. External database mode via DATABASE_URL was deprecated in 3.0.0 and removed in 4.0.0, which refuses to start when no volume is mounted at PGDATA. PostgreSQL 16 runs embedded inside the single application container, socket-only.