From 77f571fbcf86a2cd7763d4e358aa85de403d0a8c Mon Sep 17 00:00:00 2001 From: nmemmert <67961292+nmemmert@users.noreply.github.com> Date: Tue, 14 Jul 2026 09:30:54 -0400 Subject: [PATCH] Rewrite README for bare-metal install and current feature set Replaces outdated container-focused README with accurate docs: one-line install, 2FA, backup/restore migration guide, data storage layout. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 402 ++++++++++++------------------------------------------ 1 file changed, 88 insertions(+), 314 deletions(-) diff --git a/README.md b/README.md index 2c440b6..5bd39a1 100644 --- a/README.md +++ b/README.md @@ -1,352 +1,126 @@ # Capsule by NeCloud -A modern, privacy-focused envelope budgeting application built with Next.js, TypeScript, and Tailwind CSS. Capsule helps you manage your finances using the traditional envelope budgeting method in a beautiful, digital format with complete control over your data. +A privacy-focused envelope budgeting app built with Next.js, TypeScript, and Tailwind CSS. All data is stored encrypted on your own server — no cloud, no tracking, no subscriptions. -**🔒 Privacy-First Design**: All your financial data is stored locally on your server in encrypted files. No cloud services, no data sharing, complete control over your information. +## Quick Install + +One command on any Linux cloud server (Ubuntu, Debian, Rocky, RHEL): + +```bash +curl -fsSL https://raw.githubusercontent.com/nmemmert/budget/master/install.sh | sudo bash +``` + +This will: +- Install Node.js 20 if needed (via NodeSource) +- Clone the repo to `/opt/capsule` +- Build the app +- Create and start a `capsule` systemd service on port **7654** + +Re-run the same command to upgrade in place. + +**After install, open:** `http://your-server-ip:7654` + +### Useful commands + +```bash +systemctl status capsule # check if running +systemctl restart capsule # restart +journalctl -u capsule -f # view logs +``` + +--- ## Features -### 🎨 Customizable Dashboard -- **Drag & Drop Sections**: Rearrange dashboard sections exactly how you want them -- **Show/Hide Controls**: Toggle visibility of dashboard components -- **5 Summary Cards**: Quick view of Assets, Debt, Balance, Envelopes, and Transactions -- **Analytics Charts**: Income vs Expenses, Budget Alerts, Assets vs Debt breakdown -- **Quick Actions**: One-click access to common tasks -- **Budget Progress**: Visual tracking of monthly spending against budget +### Security & Privacy +- **Encrypted local storage** — AES-GCM encryption, data never leaves your server +- **bcrypt password hashing** — cost factor 12 +- **Two-factor authentication (TOTP)** — enable in Settings → Password & Security; works with Google Authenticator, Authy, or any TOTP app +- **Session tokens** — secure session management -### 🔐 Security & Privacy -- **Secure Local Storage**: File-based storage with AES-GCM encryption -- **User Authentication**: Secure sign-up and login with password hashing -- **No Cloud Dependencies**: Your data never leaves your server +### Envelope Budgeting +- Create envelopes for spending categories with budget limits +- Overspend warnings (red ring + banner when over budget) +- Color-coded progress bars (green → yellow → red) +- Auto-categorization rules — keyword-based, with a "Run Rules Now" button to apply to existing transactions -### 💰 Smart Money Management -- **Envelope Budgeting**: Create and manage budget envelopes for different spending categories -- **Multiple Account Support**: Track checking, savings, credit cards, mortgages, loans, and investments -- **Account Normalization**: Liabilities (credit cards, loans) automatically display as negative balances -- **Net Worth Tracking**: Automatic calculation of assets minus debt -- **Get Paid Feature**: Automatically distribute income across envelopes +### Accounts & Transactions +- Multiple account types: checking, savings, credit cards, mortgages, loans, investments +- Liabilities display as negative balances; net worth calculated automatically +- Import from CSV, OFX, QFX, or QBO bank exports (with duplicate detection) +- Manual entry and recurring transactions +- Edit, delete, and filter transactions -### 📊 Transaction Management -- **Multiple Input Methods**: - - **Manual Entry**: Add individual transactions with full details - - **File Import**: Import from bank exports (CSV, OFX, QFX, QBO) - - **Get Paid**: Record income with automatic envelope distribution -- **Transaction Editing**: Full edit capabilities with real-time updates -- **Recent History**: Quick view of latest transactions -- **Smart Filtering**: View transactions by account, envelope, or date range +### Get Paid +- Record income and auto-distribute across envelopes by percentage +- Paycheck schedule with next payday preview (weekly, biweekly, semi-monthly, monthly) -### 📈 Analytics & Insights -- **Income vs Expenses**: Monthly income and spending comparison -- **Budget Alerts**: Notifications for envelopes over 80% or overspent -- **Daily Spending Chart**: 7-day spending visualization -- **Envelope Progress**: Color-coded spending progress for each category -- **Account Balances**: Visual breakdown of all account balances +### Backup & Restore +- **Settings → Backup & Restore** +- Download a `.tar.gz` of all server data (users, sessions, all budget data) +- Upload a backup to restore — works for migrating to a new server +- Previous data is kept as `.bak` before any restore -### 🎨 Beautiful Design -- **Capsule Branding**: Modern cloud-themed design with professional color palette -- **Responsive Layout**: Seamless experience on desktop, tablet, and mobile -- **Customizable Colors**: Choose colors for envelopes and visual organization -- **Interactive Elements**: Clickable cards, hover effects, and smooth transitions -- **Data Export**: Export to CSV or JSON formats for backup or analysis +### Account Sharing +- Share individual accounts with other registered users (read-only view) -## Brand Colors +### Dashboard +- Customizable layout (drag & drop, show/hide sections) +- Income vs Expenses, Budget Alerts, Net Worth, Envelope Spending charts +- Mobile bottom tab bar -- **Primary Blue**: #1E73BE - Main brand color -- **Finance Green**: #28A745 - Positive balances and income -- **Cloud Blue**: #A7D8F8 - Secondary accents -- **Dark Navy**: #0F2C4C - Text and headers -- **Neutral Gray**: #F4F4F4 - Backgrounds +--- -## Getting Started +## Migrating to a New Server -### Container Installation (Recommended for Rocky Linux + Cockpit) +1. On the old server: **Settings → Backup & Restore → Download Backup** +2. On the new server: run the install command above +3. Sign in, then go to **Settings → Backup & Restore → Choose Backup File** and upload the `.tar.gz` +4. You'll be signed out — sign back in with your original credentials -**Option 1: Clone and Deploy** (works for private/public repos) +--- -```bash -git clone https://github.com/nmemmert/budget.git capsule-budget -cd capsule-budget -./deploy.sh -``` +## Data Storage -**Option 2: One-Line Install** (public repos only) +Everything lives in `/opt/capsule/data/`: -```bash -curl -fsSL https://raw.githubusercontent.com/nmemmert/budget/master/install.sh | bash -``` +| File | Contents | +|------|----------| +| `users.json` | Email + hashed passwords, 2FA secrets | +| `sessions.json` | Active login sessions | +| `{userId}.json` | Each user's budget data (AES-GCM encrypted) | +| `shares.json` | Account sharing records | -**Access at:** `http://localhost:7654` or `http://your-device-ip:7654` +Back up this directory to protect your data. No external database required. -### Rocky Linux + Cockpit + Podman +--- -```bash -sudo dnf install -y podman podman-compose cockpit cockpit-podman git -sudo systemctl enable --now cockpit.socket +## Development -git clone https://github.com/nmemmert/budget.git capsule-budget -cd capsule-budget -./deploy.sh -``` - -Manage the container in Cockpit at `https://your-server:9090` under **Podman Containers**. - -### Manual Installation (Development) - -If you want to run from source: - -1. Clone the repository: ```bash git clone https://github.com/nmemmert/budget.git cd budget -``` - -2. Install dependencies: -```bash npm install +npm run dev # http://localhost:7654 ``` -3. Run the development server: ```bash -npm run dev +npm run build # production build +npm run start # production server +npm run lint # ESLint ``` -4. Open [http://localhost:7654](http://localhost:7654) in your browser +--- -### First Time Setup +## Tech Stack -1. **Create Account**: Click "Sign Up" to create your secure account -2. **Setup Wizard**: Complete the guided setup: - - Add your first account (checking, savings, etc.) - - Create initial budget envelopes with default budgets - - Configure income allocation rules -3. **Customize Dashboard**: Click the ⚙️ Customize button to: - - Drag and drop sections to rearrange - - Show or hide dashboard components - - Create your perfect financial overview +- **Next.js** (App Router) + **TypeScript** +- **Tailwind CSS v4** +- **Node.js `crypto`** — AES-GCM encryption, TOTP (no external crypto deps) +- **bcryptjs** — password hashing -## Dashboard Customization - -### Available Sections - -1. **Summary Cards** - Quick overview of total assets, debt, balance, envelope count, and transaction count -2. **Analytics Charts** - Six detailed charts including income/expenses, alerts, and spending patterns -3. **Budget Progress** - Visual progress bar showing monthly budget utilization -4. **Quick Actions** - Fast access buttons for common tasks -5. **Recent Transactions** - Latest 5 transactions with edit/delete options - -### How to Customize - -- Click **⚙️ Customize** at the top of the dashboard -- **Drag & Drop**: Click and hold the ⋮⋮ handle to drag sections -- **Up/Down Arrows**: Use ▲ ▼ buttons for precise positioning -- **Toggle Visibility**: Check/uncheck boxes to show or hide sections -- Your preferences are automatically saved - -## Storage System - -This application uses a **local file-based storage system** instead of cloud databases: - -- All user data stored in `/data` directory as encrypted JSON files -- User credentials hashed with SHA-256 -- Budget data encrypted with AES-GCM encryption -- Complete data portability and privacy - -For detailed information about the storage system, see [FILE_STORAGE.md](./FILE_STORAGE.md). - -## Available Scripts - -- `npm run dev` - Start the development server on port 7654 -- `npm run build` - Build the project for production -- `npm run start` - Start the production server -- `npm run lint` - Run ESLint for code quality checks - -## Project Structure - -``` -src/ -├── app/ -│ ├── layout.tsx # Root layout with Capsule branding -│ ├── page.tsx # Main dashboard with customization -│ ├── globals.css # Global styles with brand colors -│ └── api/ -│ ├── auth/ # Authentication endpoints -│ └── data/ # Data persistence endpoints -├── components/ -│ ├── AccountManagement.tsx # Account CRUD operations -│ ├── DashboardCharts.tsx # Analytics visualizations -│ ├── DataInput.tsx # Transaction entry forms -│ ├── EnvelopeCreate.tsx # Envelope creation -│ ├── EnvelopeEdit.tsx # Envelope editing -│ ├── GetPaid.tsx # Income distribution -│ ├── SetupWizard.tsx # First-time setup flow -│ ├── TransactionEdit.tsx # Transaction editing -│ └── ... # Additional components -├── lib/ -│ ├── authService.ts # Authentication logic -│ ├── dataService.ts # Data persistence layer -│ ├── fileStorage.ts # Encrypted file storage -│ └── crypto.ts # Encryption utilities -data/ # User data storage (gitignored) -public/ -├── capsule-icon.svg # App favicon -└── images/ - └── capsule-logo.svg # Brand logo -``` - -## Technologies Used - -- **Next.js 16** - React framework with App Router and Turbopack -- **TypeScript** - Type-safe JavaScript -- **Tailwind CSS 4** - Utility-first CSS framework with custom properties -- **React 19** - UI library with modern hooks -- **Node.js Crypto** - AES-GCM encryption and SHA-256 password hashing -- **ESLint** - Code quality and consistency - -## Key Features in Detail - -### Envelope Budgeting System -The envelope method divides your income into categories (envelopes), each with a budget allocation. When you spend money, it's deducted from the appropriate envelope, helping you stay within your budget limits. - -### Automatic Income Distribution -The "Get Paid" feature automatically splits your paycheck across envelopes based on percentages you set during setup. For example: -- Rent: 40% -- Groceries: 15% -- Savings: 20% -- etc. - -### Visual Progress Tracking -Each envelope shows: -- Allocated amount (your budget) -- Spent amount (what you've used) -- Remaining balance -- Progress bar with color coding (green → yellow → red as you approach limits) - -### Smart Alerts -Get notified when: -- An envelope reaches 80% of its budget -- An envelope is overspent -- Your daily spending exceeds normal patterns - -## How to Use - -### Dashboard Navigation - -The dashboard provides a complete overview of your finances: - -- **Summary Cards**: Click any card to navigate to the detailed view - - Assets → View all asset accounts - - Debt → View all liability accounts - - Balance → View all accounts - - Envelopes → Manage budget envelopes - - Transactions → View transaction history - -- **Analytics**: Monitor your financial health with real-time charts - - Income vs Expenses (current month) - - Budget Alerts (overspent or near-limit envelopes) - - Assets vs Debt breakdown with Net Worth - - Envelope spending progress - - Account balance distribution - - Daily spending trends (last 7 days) - -### Managing Money - -1. **Record Income**: - - Click "💰 Get Paid" button - - Enter amount and select deposit account - - Funds are automatically distributed to envelopes based on allocation percentages - -2. **Track Expenses**: - - Use "Manual Entry" for individual transactions - - Import bank files for bulk transaction entry - - Assign each expense to an envelope for tracking - -3. **Monitor Budgets**: - - View envelope spending progress in real-time - - Get alerts when approaching or exceeding budget limits - - Track monthly spending against allocated amounts - -### Account Types - -Capsule supports multiple account types with automatic balance normalization: - -- **Assets** (positive balances): - - Checking accounts - - Savings accounts - - Investment accounts - -- **Liabilities** (negative balances): - - Credit cards - - Mortgages - - Loans - -Your Net Worth is automatically calculated as: Total Assets - Total Debt - -## Data Import - -### Supported File Formats - -- **CSV**: Comma-separated values with columns: Date, Amount, Description, Category (optional) -- **OFX/QFX**: Standard bank export formats from most financial institutions -- **QBO**: QuickBooks Online format -- **PDF**: Coming soon (statement parsing) - -### CSV Format Example -```csv -Date,Amount,Description,Category -2024-01-15,-25.50,Weekly groceries,Groceries -2024-01-16,-12.00,Gas station,Transportation -2024-01-17,1500.00,Salary deposit,Income -``` - -## Advanced Features - -### Transaction Editing -- Click the edit icon (pencil) next to any transaction to modify its details -- Update amount, description, date, and envelope assignment -- Changes automatically update envelope spending calculations - -### Envelope Management -- Click "Add Envelope" to create new budget categories -- Choose from multiple colors for visual organization -- Set custom budget allocations for each envelope - -### Data Export -- Export all transactions and envelopes to CSV for spreadsheet analysis -- Export to JSON format for data backup or integration -- Includes complete transaction history and envelope details - -## Deployment - -### Self-Hosted Deployment (Recommended) - -Capsule is designed for self-hosted deployment on Rocky Linux, ZimaOS, and similar platforms. - -**Quick Deploy:** -```bash -./deploy.sh -``` - -See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed Podman/Docker deployment instructions. - -**Features:** -- Podman/Docker containerization for easy deployment -- Persistent data storage in `./data` directory -- Health checks and auto-restart -- Encrypted local storage (no cloud required) - -**Access:** -- Default port: 7654 -- Local: `http://localhost:7654` -- Network: `http://your-device-ip:7654` - -## Contributing - -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Run tests and linting -5. Submit a pull request +--- ## License -This project is licensed under the MIT License. +MIT