skills.rest
maxlainz
maxlainzCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

futurefin-build-and-env

Recreate the FutureFin development environment and diagnose build and environment failures.

1|Updated May 2, 2026
Search Tags:#Docker#troubleshooting#postgresql#build#dev environment#rust#vite
One-click install
npx skills add https://github.com/maxlainz/FutureFin --skill futurefin-build-and-env-maxlainz
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: futurefin-build-and-env
Source: https://github.com/maxlainz/FutureFin/tree/main/.claude/skills/futurefin-build-and-env
Command: npx skills add https://github.com/maxlainz/FutureFin --skill futurefin-build-and-env-maxlainz

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Setting up the FutureFin stack from a fresh clone involves coordinating Rust, Node.js, Docker Compose, and PostgreSQL, and small misconfigurations (port clashes, stale .env variables, migration checksum mismatches, missing volumes) produce cryptic failures. This Skill provides a verified runbook that takes a bare machine to a working split-dev environment and maps every known symptom to its cause and fix. ## Core Features & Use Cases - Environment recreation: Step-by-step setup of the split-dev workflow (cargo run API on 8081 plus Vite dev server on 8080 against docker-compose.dev.yml), API-only mode, and the ff-test-db integration test database on port 5433. - Build command reference: Exact cargo build/test and npm typecheck/lint/build/test commands, plus the local self-contained Docker image build via ./scripts/build-local-image.sh with the mandatory --load flag. - Trap diagnosis: Ten documented symptom-to-cause-to-fix entries covering connection refused on 5432, DATABASE_URL leaking into the production image, VersionMismatch migration errors, stale UI being served, and the no-persistent-volume startup guard. - Use Case: After cloning FutureFin on a new machine, ask the agent to bring up the dev environment; it will create .env, start the dev Postgres container, launch the API and Vite, and resolve any port or proxy conflicts encountered. ## Quick Start Set up the FutureFin development environment on this machine from a fresh clone and get the split-dev stack running.

Frequently Asked Questions about futurefin-build-and-env

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

FAQPage Schema
How do I set up the FutureFin development environment from a fresh clone?▼

Copy .env.example to .env and uncomment the three dev vars, run ./scripts/dev-db.sh to start the dev Postgres container, then run cargo run in apps/api and npm run dev:web. The API listens on port 8081 and Vite serves the UI on 8080 with API proxying.

How do I run FutureFin integration tests locally?▼

Start a dedicated Postgres container named ff-test-db on port 5433 with the futurefin_test credentials, then run cargo test --workspace with TEST_DATABASE_URL pointing at it. Each test creates its own ff_test_<uuid> schema, applies all migrations, and runs against the real router.

Why does FutureFin fail with connection refused on port 5432?▼

The dev database container was never started. Since version 3.0.0 the production compose has no database service because PostgreSQL runs inside the app container over a Unix socket, so only docker-compose.dev.yml publishes 127.0.0.1:5432 for development.

Why does the FutureFin container exit with no persistent volume is mounted?▼

This is a deliberate anti-data-loss guard, not a bug. The entrypoint checks with mountpoint that /var/lib/postgresql/data is a real volume before starting, since the image declares no VOLUME instruction. Run through compose or pass -v, or set FUTUREFIN_ALLOW_EPHEMERAL_DB=1 for throwaway containers.

How do I fix a migration checksum mismatch error in sqlx?▼

A migration file changed after being applied to the database. For a dev database only, delete the offending version row from _sqlx_migrations via psql and restart the API, or recreate the dev database volume. The auto-repair loop was removed in v1.3.0, so mismatches must be fixed manually.

When should I not use this build and environment runbook?▼

Do not use it for cataloging environment variables or configuration flags, production deploys, upgrades, rollbacks and backups, or writing and extending tests. Those belong to the futurefin-config-and-flags, futurefin-run-and-operate, and futurefin-validation-and-qa skills respectively.

Related Skills

Explore More Software Engineering Skills→
raphaelmansuyraphaelmansuy
2.1k

makefile-dev-workflow

Manages EdgeQuake development services, tests, and builds through unified Makefile targets.

Community
Intermediate
cyhinversecyhinverse

deployment-procedures

Guide production deployments through a five-phase workflow with rollback readiness.

Community
Advanced
semicolon-devteamsemicolon-devteam

scaffold-compose

Adds templated service definitions to Docker Compose files with validation via docker-compose.

Official
Advanced
robot-dennyrobot-denny

tdd-principles

Guides writing durable tests that assert observable behavior rather than implementation artifacts.

Community
Intermediate