Skip to content
Klutch.sh Docs

Deploying Family Accounting Tool

Introduction

Family Accounting Tool (FAT) is a powerful, self-hosted web application designed to help families and individuals track their finances, manage budgets, and gain insights into spending habits. Built with modern web technologies, it provides an intuitive interface for personal financial management without relying on third-party cloud services.

Family Accounting Tool offers comprehensive financial management features:

  • Multi-Account Support - Track checking, savings, credit cards, and investment accounts
  • Transaction Management - Easy entry and categorization of income and expenses
  • Budget Planning - Set monthly budgets by category and track spending
  • Reporting & Analytics - Visualize spending patterns with charts and graphs
  • Recurring Transactions - Automate entry of regular bills and income
  • Multi-Currency Support - Handle accounts in different currencies
  • Data Import/Export - Import transactions from CSV files and bank statements
  • Search & Filter - Quickly find transactions with powerful search tools
  • Multi-User Access - Share accounts with family members with role-based permissions
  • Privacy-Focused - Your data stays on your own server

Why Deploy Family Accounting Tool on Klutch.sh?

Deploying Family Accounting Tool on Klutch.sh provides several advantages:

  • Complete Privacy - Your financial data never leaves your control
  • Fast Deployment - Get up and running in minutes with automatic Dockerfile detection
  • Persistent Storage - Reliable database and file storage for all your financial records
  • HTTPS by Default - Bank-grade encryption for all your financial data
  • Custom Domains - Access your finances at your own domain
  • Automated Backups - Integrated volume backup capabilities
  • Scalable - Handles years of transaction history without slowdown
  • Cost-Effective - Predictable monthly pricing for complete financial privacy

Prerequisites

Before starting, ensure you have:

Preparing Your Family Accounting Tool Repository

1. Create a Project Directory

Start by creating a new directory for your Family Accounting Tool deployment:

Terminal window
mkdir family-accounting-tool-klutch
cd family-accounting-tool-klutch
git init

2. Create the Dockerfile

Create a Dockerfile in your project root with the following configuration:

# Multi-stage build for Family Accounting Tool
FROM node:18-alpine AS builder


# Install build dependencies
RUN apk add --no-cache python3 make g++ git


# Set working directory
WORKDIR /app


# Clone Family Accounting Tool repository
ARG FAT_VERSION=main
RUN git clone https://github.com/range-of-motion/family-accounting-tool.git . && \
    git checkout ${FAT_VERSION}


# Install dependencies
RUN npm ci --only=production


# Build the application
RUN npm run build


# Production stage
FROM node:18-alpine


# Install runtime dependencies
RUN apk add --no-cache \
    postgresql-client \
    curl


# Create app user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001


# Set working directory
WORKDIR /app


# Copy built application from builder
COPY --from=builder --chown=nodejs:nodejs /app/package*.json ./
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/build ./build
COPY --from=builder --chown=nodejs:nodejs /app/public ./public
COPY --from=builder --chown=nodejs:nodejs /app/prisma ./prisma


# Copy startup script
COPY --chown=nodejs:nodejs docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh


# Create data directory
RUN mkdir -p /app/data && chown -R nodejs:nodejs /app/data


# Switch to non-root user
USER nodejs


# Expose port 3000
EXPOSE 3000


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"


# Start application
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["node", "build"]

3. Create the Docker Entrypoint Script

Create a docker-entrypoint.sh file to handle database migrations and startup:

#!/bin/sh
set -e


echo "🚀 Starting Family Accounting Tool..."


# Wait for database to be ready
echo "⏳ Waiting for PostgreSQL to be ready..."
until pg_isready -h $DATABASE_HOST -p ${DATABASE_PORT:-5432} -U $DATABASE_USER; do
  echo "Waiting for database..."
  sleep 2
done


echo "✅ PostgreSQL is ready!"


# Run database migrations
echo "🔄 Running database migrations..."
npx prisma migrate deploy


# Generate Prisma client
echo "🔧 Generating Prisma client..."
npx prisma generate


echo "✨ Starting application..."
exec "$@"

4. Create Environment Template

Create a .env.example file for reference:

# Database Configuration
DATABASE_URL=postgresql://username:password@database-host:5432/family_accounting_tool


# Application Configuration
NODE_ENV=production
PORT=3000
BASE_URL=https://example-app.klutch.sh


# Session Configuration (generate a random string for production)
SESSION_SECRET=your-super-secret-session-key-change-this


# Optional: Email Configuration (for password resets)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password


# Optional: Currency API (for exchange rates)
CURRENCY_API_KEY=your-api-key

5. Create a .dockerignore File

Create a .dockerignore file to exclude unnecessary files:

.git
.gitignore
.env
.env.*
node_modules
npm-debug.log
README.md
.DS_Store
.vscode
.idea
*.md
dist
build
.next
coverage

6. Create a .gitignore File

Create a .gitignore to protect sensitive files:

# Environment files
.env
.env.*


# Dependencies
node_modules/


# Build outputs
build/
dist/
.next/


# Database
*.db
*.sqlite
data/


# OS files
.DS_Store
Thumbs.db


# IDE
.vscode/
.idea/
*.swp
*.swo


# Logs
logs/
*.log
npm-debug.log*

7. Initialize Git and Push to GitHub

Initialize your repository and push to GitHub:

Terminal window
git add .
git commit -m "Initial Family Accounting Tool deployment setup"
git branch -M main
git remote add origin https://github.com/yourusername/family-accounting-tool-klutch.git
git push -u origin main

Deploying on Klutch.sh

Now that your repository is ready, deploy Family Accounting Tool on Klutch.sh:

  1. Navigate to the Klutch.sh Dashboard

    Go to klutch.sh/app and log into your account.

  2. Create a New Project

    Click “New Project” and give it a descriptive name like family-finances.

  3. Create a New App

    Within your project, click “New App” and select your GitHub repository containing the Family Accounting Tool Dockerfile.

  4. Configure Deployment Settings

    • Branch: Select main (or your preferred deployment branch)
    • Traffic Type: Select HTTP (Family Accounting Tool is a web application)
    • Port: Set to 3000 (the internal port the application listens on)

  5. Configure Environment Variables

    Family Accounting Tool requires several environment variables. Add the following in the Klutch.sh dashboard:

    DATABASE_URL=postgresql://fatuser:your_secure_password@your-postgres-app.klutch.sh:8000/family_accounting_tool
    NODE_ENV=production
    PORT=3000
    BASE_URL=https://example-app.klutch.sh
    SESSION_SECRET=generate-a-long-random-string-here
    DATABASE_HOST=your-postgres-app.klutch.sh
    DATABASE_PORT=8000
    DATABASE_USER=fatuser
    DATABASE_NAME=family_accounting_tool

    Important: Replace the database connection details with your actual PostgreSQL deployment. See our PostgreSQL deployment guide for setting up a database.

    To generate a secure session secret, you can run:

    Terminal window
    node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

  6. Attach Persistent Volumes

    Family Accounting Tool requires persistent storage for uploaded files and cached data:

    • Uploaded Documents: /app/data (10GB recommended)

    Click “Add Volume”:

    1. Mount Path: /app/data, Size: 10GB

  7. Deploy the Application

    Click “Deploy” to start the deployment. Klutch.sh will automatically detect your Dockerfile, build the image, and deploy your container.

  8. Monitor the Deployment

    Watch the build logs in real-time to ensure everything deploys correctly. The initial build may take 5-10 minutes as dependencies are installed.

Initial Family Accounting Tool Setup

Once deployed, complete the initial setup:

1. Access the Application

Navigate to your deployed app URL (e.g., https://example-app.klutch.sh) in your browser.

2. Create Your First User

On the first visit, you’ll be prompted to create an administrator account:

  • Email: Your email address
  • Password: Choose a strong password (min 12 characters)
  • Name: Your full name

3. Configure Basic Settings

After logging in, navigate to Settings to configure:

General Settings:

Application Name: Family Finances
Currency: USD (or your preferred currency)
Date Format: MM/DD/YYYY (or your preferred format)
First Day of Week: Sunday/Monday

Localization:

Language: English
Timezone: America/New_York (or your timezone)
Number Format: 1,234.56

4. Set Up Your First Account

Create your first financial account:

  1. Navigate to **Accounts** → **Add Account**
  2. Configure account details: 
    Account Name: Checking Account
    Account Type: Checking
    Currency: USD
    Opening Balance: 1000.00
    Bank Name: Your Bank
    Account Number: ****1234 (last 4 digits)
  3. Click **"Create Account"**

Configuration

Database Configuration

Family Accounting Tool uses PostgreSQL for data storage. The connection is configured via environment variables:

DATABASE_URL=postgresql://username:password@host:port/database

For Klutch.sh PostgreSQL deployments, use port 8000:

DATABASE_URL=postgresql://fatuser:password@postgres-app.klutch.sh:8000/family_accounting_tool

Environment Variables Reference

VariableDescriptionExampleRequired
DATABASE_URLFull PostgreSQL connection stringpostgresql://user:pass@host:5432/dbYes
DATABASE_HOSTPostgreSQL hostpostgres-app.klutch.shYes
DATABASE_PORTPostgreSQL port8000Yes
DATABASE_USERDatabase usernamefatuserYes
DATABASE_NAMEDatabase namefamily_accounting_toolYes
NODE_ENVApplication environmentproductionYes
PORTApplication port3000Yes
BASE_URLPublic application URLhttps://example-app.klutch.shYes
SESSION_SECRETSession encryption keyrandom-64-char-stringYes
SMTP_HOSTEmail server hostsmtp.gmail.comNo
SMTP_PORTEmail server port587No
SMTP_USEREmail usernameuser@gmail.comNo
SMTP_PASSEmail passwordapp-passwordNo

Custom Domain Setup

To use your own domain with Family Accounting Tool:

  1. Go to your app settings in the Klutch.sh dashboard
  2. Navigate to the “Domains” section
  3. Add your custom domain (e.g., finances.yourdomain.com)
  4. Update your DNS records as shown
  5. Update the BASE_URL environment variable to your custom domain

Learn more in our Custom Domains documentation.

Using Family Accounting Tool

Managing Accounts

Add a New Account:

  1. Navigate to **Accounts** → **Add Account**
  2. Fill in account details: - Account name - Account type (Checking, Savings, Credit Card, etc.) - Currency - Opening balance - Optional: Bank information
  3. Click **"Create"**

Transfer Between Accounts:

1. Go to Transactions → New Transaction
2. Select Type: Transfer
3. From Account: Checking Account
4. To Account: Savings Account
5. Amount: $500.00
6. Date: Today
7. Click "Create Transaction"

Recording Transactions

Add Income:

Type: Income
Account: Checking Account
Category: Salary
Amount: $3,000.00
Date: 12/15/2025
Description: December paycheck

Add Expense:

Type: Expense
Account: Credit Card
Category: Groceries
Amount: $125.50
Date: 12/18/2025
Description: Weekly grocery shopping
Merchant: Whole Foods

Creating Budgets

Set up monthly budgets to track spending:

  1. Navigate to **Budgets** → **Create Budget**
  2. Configure budget: 
    Budget Name: December 2025
    Period: Monthly
    Start Date: 12/01/2025
    Categories:
      - Groceries: $600/month
      - Dining Out: $200/month
      - Entertainment: $150/month
      - Utilities: $300/month
      - Transportation: $250/month
  3. Click **"Create Budget"**

Importing Transactions

Family Accounting Tool supports importing transactions from CSV files:

  1. Export transactions from your bank as CSV
  2. Navigate to **Transactions** → **Import**
  3. Upload your CSV file
  4. Map CSV columns to transaction fields: 
    Date Column → Date
    Description Column → Description
    Amount Column → Amount
    Category Column → Category (optional)
  5. Review and confirm the import
  6. Click **"Import Transactions"**

Generating Reports

Monthly Spending Report:

  1. Navigate to **Reports** → **Spending by Category**
  2. Select date range: Current month
  3. View pie chart and detailed breakdown
  4. Export to PDF or CSV if needed

Income vs. Expenses:

1. Go to Reports → Income vs. Expenses
2. Select time period: Last 6 months
3. View trend line graph
4. Analyze savings rate

Net Worth Tracking:

1. Go to Reports → Net Worth
2. View total assets vs. liabilities
3. Track net worth over time
4. Export report for financial planning

Production Best Practices

Security Hardening

1. Use Strong Passwords

Enforce strong password requirements:

  • Minimum 12 characters
  • Mix of uppercase, lowercase, numbers, and symbols
  • No common words or patterns
  • Use a password manager

2. Enable Two-Factor Authentication

If available in your version, enable 2FA for all users:

Settings → Security → Two-Factor Authentication → Enable

3. Regular Security Updates

Keep Family Accounting Tool updated to the latest version. Update your Dockerfile:

ARG FAT_VERSION=v1.2.3  # Update to latest stable version

Then redeploy through Klutch.sh.

4. Secure Session Secret

Use a cryptographically secure session secret:

Terminal window
# Generate a new secret
openssl rand -hex 32

Never commit your session secret to version control.

5. HTTPS Only

Ensure all traffic uses HTTPS. Klutch.sh provides this by default, but verify in your environment variables:

BASE_URL=https://example-app.klutch.sh  # Not http://

6. Restrict Database Access

Configure your PostgreSQL database to only accept connections from your application:

  • Use strong database passwords
  • Don’t expose the database publicly
  • Regular database password rotation

Database Optimization

1. Regular Backups

Set up automated database backups. For Klutch.sh PostgreSQL deployments, enable automatic backups in the dashboard.

2. Database Maintenance

Periodically optimize your database:

-- Connect to your database
psql $DATABASE_URL


-- Vacuum and analyze
VACUUM ANALYZE;


-- Check table sizes
SELECT
    schemaname,
    tablename,
    pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

3. Index Optimization

Ensure critical queries have proper indexes. Check slow queries:

-- Enable slow query logging
ALTER DATABASE family_accounting_tool SET log_min_duration_statement = 1000;


-- Review slow queries
SELECT query, calls, total_time, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

4. Archive Old Data

For better performance with years of data:

  • Archive transactions older than 5 years
  • Keep archived data in separate tables
  • Maintain access for reporting when needed

Performance Optimization

1. Enable Caching

Family Accounting Tool may support caching. Configure if available:

REDIS_URL=redis://redis-app.klutch.sh:8000
CACHE_ENABLED=true
CACHE_TTL=3600

2. Optimize Assets

The Dockerfile already includes production optimizations:

  • Minified JavaScript and CSS
  • Compressed images
  • Gzip compression

3. Database Connection Pooling

Configure connection pooling in production:

DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=10
DATABASE_CONNECTION_TIMEOUT=30000

4. Monitor Performance

Track application performance:

  • Response times
  • Database query performance
  • Memory usage
  • CPU utilization

Backup Strategy

1. Database Backups

Implement automated daily backups:

# Example backup script (run on PostgreSQL server)
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
pg_dump $DATABASE_URL > backup_$DATE.sql
gzip backup_$DATE.sql


# Keep last 30 days of backups
find . -name "backup_*.sql.gz" -mtime +30 -delete

2. Application Data Backups

Backup the /app/data volume containing uploaded files:

  • Daily incremental backups
  • Weekly full backups
  • Store backups in a separate location

3. Configuration Backups

Keep backups of:

  • Environment variables
  • Database schema
  • Application settings

4. Backup Testing

Regularly test backup restoration:

Terminal window
# Test database restore
psql $DATABASE_URL < backup_20251220.sql


# Verify data integrity
# Check transaction counts
# Verify account balances

5. Backup Retention Policy

  • Daily backups: Keep for 7 days
  • Weekly backups: Keep for 4 weeks
  • Monthly backups: Keep for 12 months
  • Yearly backups: Keep for 7 years (for tax purposes)

Monitoring and Logging

1. Application Logs

Monitor application logs for errors:

Terminal window
# View logs in Klutch.sh dashboard
# Or if you have terminal access:
tail -f /var/log/family-accounting-tool.log

2. Error Tracking

Set up error tracking with services like:

3. Uptime Monitoring

Monitor application availability:

4. Performance Monitoring

Track application performance metrics:

  • Average response time
  • Database query performance
  • Memory and CPU usage
  • Transaction processing speed

Scaling Considerations

1. Vertical Scaling

For increased performance, upgrade your Klutch.sh plan:

  • More CPU cores for faster transaction processing
  • Additional RAM for caching and better performance
  • Faster storage I/O for database operations

2. Database Optimization

  • Add indexes to frequently queried columns
  • Implement database connection pooling
  • Consider read replicas for reporting

3. Caching Strategy

Implement caching for frequently accessed data:

  • User session data
  • Account balances
  • Category lists
  • Recent transactions

Troubleshooting

Installation Issues

Problem: “Cannot connect to database”

Solution:

  • Verify database credentials in environment variables
  • Ensure PostgreSQL deployment is running
  • Check that the database exists and user has proper permissions
  • For Klutch.sh PostgreSQL deployments, ensure you’re using port 8000
Terminal window
# Test database connection
psql postgresql://fatuser:password@postgres-app.klutch.sh:8000/family_accounting_tool

Problem: “Database migration failed”

Solution:

  • Check database logs for errors
  • Ensure database user has CREATE TABLE permissions
  • Verify DATABASE_URL is correctly formatted
  • Try running migrations manually:
Terminal window
# Exec into container
npx prisma migrate deploy

Problem: “Session secret not set”

Solution:

  • Generate a secure session secret:
Terminal window
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
  • Add it to your environment variables as SESSION_SECRET

Performance Issues

Problem: Slow transaction loading

Solution:

  • Check database query performance
  • Add indexes to frequently queried columns
  • Implement pagination for large transaction lists
  • Archive old transactions
-- Add index for date queries
CREATE INDEX idx_transactions_date ON transactions(date DESC);


-- Add index for account queries
CREATE INDEX idx_transactions_account ON transactions(account_id);

Problem: High memory usage

Solution:

  • Reduce database connection pool size
  • Implement caching for frequently accessed data
  • Optimize database queries
  • Consider upgrading your Klutch.sh plan

Data Issues

Problem: Incorrect account balances

Solution:

  • Recalculate balances from transactions
  • Check for duplicate transactions
  • Verify all transactions are properly recorded
  • Run database integrity checks

Problem: Missing transactions after import

Solution:

  • Verify CSV format matches expected structure
  • Check date format in CSV file
  • Ensure amount column uses proper decimal format
  • Review import logs for errors

Login Issues

Problem: Cannot log in after password change

Solution:

  • Clear browser cookies and cache
  • Try password reset via email
  • Check if email service is configured correctly
  • Verify SMTP settings in environment variables

Problem: “Session expired” errors

Solution:

  • Check SESSION_SECRET is set correctly
  • Increase session timeout if needed
  • Clear browser cookies
  • Restart the application

Additional Resources

Official Documentation

Financial Management Resources

Alternative Tools

Community and Support

Ready to take control of your family finances? Deploy Family Accounting Tool on Klutch.sh today and start tracking your financial journey with complete privacy and control. Need help with database setup? Check out our PostgreSQL deployment guide to get your database running first.