nate/budget
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite README for bare-metal install and current feature set

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
nmemmertandClaude Sonnet 4.6 committed 2026-07-14 09:30:54 -04:00
1 parent 028265dd60
commit 77f571fbcf
1 file changed
+88 -314
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+88 -314
View File
@@ -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