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 <noreply@anthropic.com>
This commit is contained in:
nmemmertandClaude Sonnet 4.6 committed
1 parent
028265dd60
commit
77f571fbcf
1 file changed
+88
-314
@@ -1,352 +1,126 @@
|
|||||||
# Capsule by NeCloud
|
# 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
|
## Features
|
||||||
|
|
||||||
### 🎨 Customizable Dashboard
|
### Security & Privacy
|
||||||
- **Drag & Drop Sections**: Rearrange dashboard sections exactly how you want them
|
- **Encrypted local storage** — AES-GCM encryption, data never leaves your server
|
||||||
- **Show/Hide Controls**: Toggle visibility of dashboard components
|
- **bcrypt password hashing** — cost factor 12
|
||||||
- **5 Summary Cards**: Quick view of Assets, Debt, Balance, Envelopes, and Transactions
|
- **Two-factor authentication (TOTP)** — enable in Settings → Password & Security; works with Google Authenticator, Authy, or any TOTP app
|
||||||
- **Analytics Charts**: Income vs Expenses, Budget Alerts, Assets vs Debt breakdown
|
- **Session tokens** — secure session management
|
||||||
- **Quick Actions**: One-click access to common tasks
|
|
||||||
- **Budget Progress**: Visual tracking of monthly spending against budget
|
|
||||||
|
|
||||||
### 🔐 Security & Privacy
|
### Envelope Budgeting
|
||||||
- **Secure Local Storage**: File-based storage with AES-GCM encryption
|
- Create envelopes for spending categories with budget limits
|
||||||
- **User Authentication**: Secure sign-up and login with password hashing
|
- Overspend warnings (red ring + banner when over budget)
|
||||||
- **No Cloud Dependencies**: Your data never leaves your server
|
- 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
|
### Accounts & Transactions
|
||||||
- **Envelope Budgeting**: Create and manage budget envelopes for different spending categories
|
- Multiple account types: checking, savings, credit cards, mortgages, loans, investments
|
||||||
- **Multiple Account Support**: Track checking, savings, credit cards, mortgages, loans, and investments
|
- Liabilities display as negative balances; net worth calculated automatically
|
||||||
- **Account Normalization**: Liabilities (credit cards, loans) automatically display as negative balances
|
- Import from CSV, OFX, QFX, or QBO bank exports (with duplicate detection)
|
||||||
- **Net Worth Tracking**: Automatic calculation of assets minus debt
|
- Manual entry and recurring transactions
|
||||||
- **Get Paid Feature**: Automatically distribute income across envelopes
|
- Edit, delete, and filter transactions
|
||||||
|
|
||||||
### 📊 Transaction Management
|
### Get Paid
|
||||||
- **Multiple Input Methods**:
|
- Record income and auto-distribute across envelopes by percentage
|
||||||
- **Manual Entry**: Add individual transactions with full details
|
- Paycheck schedule with next payday preview (weekly, biweekly, semi-monthly, monthly)
|
||||||
- **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
|
|
||||||
|
|
||||||
### 📈 Analytics & Insights
|
### Backup & Restore
|
||||||
- **Income vs Expenses**: Monthly income and spending comparison
|
- **Settings → Backup & Restore**
|
||||||
- **Budget Alerts**: Notifications for envelopes over 80% or overspent
|
- Download a `.tar.gz` of all server data (users, sessions, all budget data)
|
||||||
- **Daily Spending Chart**: 7-day spending visualization
|
- Upload a backup to restore — works for migrating to a new server
|
||||||
- **Envelope Progress**: Color-coded spending progress for each category
|
- Previous data is kept as `.bak` before any restore
|
||||||
- **Account Balances**: Visual breakdown of all account balances
|
|
||||||
|
|
||||||
### 🎨 Beautiful Design
|
### Account Sharing
|
||||||
- **Capsule Branding**: Modern cloud-themed design with professional color palette
|
- Share individual accounts with other registered users (read-only view)
|
||||||
- **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
|
|
||||||
|
|
||||||
## 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
|
## Data Storage
|
||||||
git clone https://github.com/nmemmert/budget.git capsule-budget
|
|
||||||
cd capsule-budget
|
|
||||||
./deploy.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
**Option 2: One-Line Install** (public repos only)
|
Everything lives in `/opt/capsule/data/`:
|
||||||
|
|
||||||
```bash
|
| File | Contents |
|
||||||
curl -fsSL https://raw.githubusercontent.com/nmemmert/budget/master/install.sh | bash
|
|------|----------|
|
||||||
```
|
| `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
|
## Development
|
||||||
sudo dnf install -y podman podman-compose cockpit cockpit-podman git
|
|
||||||
sudo systemctl enable --now cockpit.socket
|
|
||||||
|
|
||||||
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
|
```bash
|
||||||
git clone https://github.com/nmemmert/budget.git
|
git clone https://github.com/nmemmert/budget.git
|
||||||
cd budget
|
cd budget
|
||||||
```
|
|
||||||
|
|
||||||
2. Install dependencies:
|
|
||||||
```bash
|
|
||||||
npm install
|
npm install
|
||||||
|
npm run dev # http://localhost:7654
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Run the development server:
|
|
||||||
```bash
|
```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
|
- **Next.js** (App Router) + **TypeScript**
|
||||||
2. **Setup Wizard**: Complete the guided setup:
|
- **Tailwind CSS v4**
|
||||||
- Add your first account (checking, savings, etc.)
|
- **Node.js `crypto`** — AES-GCM encryption, TOTP (no external crypto deps)
|
||||||
- Create initial budget envelopes with default budgets
|
- **bcryptjs** — password hashing
|
||||||
- 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
|
|
||||||
|
|
||||||
## 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
|
## License
|
||||||
|
|
||||||
This project is licensed under the MIT License.
|
MIT
|
||||||
Reference in new issue
Block a user