Introduction

Smerio is a self-hosted personal finance application focused on privacy and multi-user collaboration. Unlike SaaS tools, Smerio is designed to be run on your own infrastructure using Docker.

Installation & Deployment

This guide explains how to deploy Smerio using the universal deployment script.

Directory Structure

Install/: Contains deployment scripts (deploy.sh) and configuration.
Install/.env: Deployment configuration (VPS IPs, Registry, etc).
Install/demo.db: Database snapshot for Demo mode.

Requirement: You need Docker and a Unix-like environment (Linux/macOS) to run the scripts.

Step 1: Configuration

1. Copy the template configuration:

cp Install/.env.template Install/.env

2. Edit Install/.env with your details (Required for Remote deployment).

Step 2: Deployment

Run the universal script:

./Install/deploy.sh

Interactive Options:

Target: Choose Local (Docker Compose) or Remote (VPS).
Mode: Choose Production, Demo (resets every 60m), or Debug.

Remote Behavior

When deploying to a VPS (Remote), the script will:

Pull your configured Docker image.
Configure Nginx and SSL (Certbot) automatically.
Secure the admin panel (block direct access to /_/).

First Steps

Create Admin Account: The first time you load the page, you will be prompted to create your admin login.
Define Your Base Currency: In Settings, choose the primary currency you use for reporting (e.g., EUR, USD, RSD).
Add Your First Asset: Go to the "Wealth" tab and click "Add Asset." Try adding your "Cash Wallet" or "Bank Account."

FAQ

Is my data encrypted?: Smerio relies on your server's security. For maximum protection, we recommend running Smerio behind a reverse proxy (like Nginx or Caddy) with HTTPS enabled.
How do I backup my data?: All your data is stored in the pb_data folder. Simply copy this folder to a safe location to create a full backup.

Application Reference

Dashboard

This is your financial command center. It aggregates data from all your Accounts, Transactions, and Portfolio assets.

Key Metrics:

Net Worth: Total Assets - Debts.
Cashflow (YTD): Total Income minus Total Expenses for the current year.
Portfolio: Brokerage and Crypto holdings.

Wealth & Accounts

Your net worth is split into Assets (what you own) and Debts (what you owe).

Field Descriptions

Field	Description
Class	Asset or Debt (Loan)?
Name	Custom display name.
Type	Category (Bank, Car, Crypto, etc).
Balance	Current funds. for Brokerage/Crypto, leave as 0 to auto-calculate.
Status	Account Status (Active/Archived).
Cur	The currency of the account.
Source	The financial institution holding the asset/debt (e.g., Bank of America).
Assigned to	The internal owner of the asset/debt. Use a personal name or a group name.
Purpose	The primary goal for this asset/debt (e.g., Spending, Emergency Fund, Education).

Transactions

Managing Records

Add: Click "Add Transaction" to record a new income or expense.
Edit: Click the pencil icon to modify a record.
Duplicate: Click the file icon to copy a transaction.
Delete: Click the trash icon to remove a record.

Filtering & Exporting

Filter: Use the "Filters" section to search by date, type, category, or amount.
Export: Click "Export CSV" to download your filtered results for external analysis.

Tips

Use Envelopes for budgeting expenses.
Use Subcategories for detailed tracking.
Smart Suggestions: The app learns your category associations over time.

Field Descriptions (Transactions)

Field	Description
Envelope (Expense)	The budget category (e.g., Groceries, Rent).
Subcategory (Expense)	Specific details (e.g., Shop Name, Item).
Payee (Income)	Person, breadwinner or employer name.
Source (Income)	Company name, type of work (freelance), gifts, or other income.
Date	Date of the transaction.
Amount	The value of the transaction.
Currency	Enter the currency you actually spent. It will be converted to your base currency.
Amount (Base)	The value in your main currency. You can manually override this.

Portfolio

Purpose & Accounts

This page tracks your investment holdings (Stocks, ETFs, Crypto). Each asset is linked to a specific Account (e.g., "Brokerage"). The total value shown here contributes to your Net Worth on the Dashboard.

Calculations

Value: Calculated as Quantity × Current Price.
Avg Price: The weighted average cost you paid per share.
Result: Calculated as (Current Price - Avg Price) × Quantity.

Updating Prices

Click Update Prices to fetch the latest market data for all your tickers. This ensures your Portfolio Value and Net Worth are always up to date.

Field Descriptions (Assets)

Field	Description
Ticker Symbol	Use Yahoo Finance symbols (e.g. AAPL).
Quantity	Number of shares or units held.
Current Price	Optional. We will try to update this value when you press "Update Prices".
Linked Account	The value of this asset will contribute to this account's balance.

Envelope Planning

Purpose

This page helps you compare your Planned Budget against your Actual Spending for the current month. Use it to stay on track and adjust your habits.

Planning Expenses

Set Budget: Enter your target amount in the "Planned" column for each envelope.
Save: Click the floppy disk icon to save your budget.
Auto-Add: New envelopes appear automatically when you categorize transactions in the Transactions page.

Interpreting Results

Actual: Total spending in this envelope for the current month.
Avg (6m): Your average monthly spending over the last 6 months (for reference).
Remaining %: Cyan (Under Budget), Pink (Over Budget).

Settings

General Settings

Set your Main Currency (e.g., USD, EUR). This is the currency used for all total calculations and reports. Changing this will trigger a recalculation of all historical data.

Global Lists

Manage your categories (Envelopes, Sources, Payees). You can Rename items or Transfer transactions from one category to another (merging them).

Component Descriptions (Category Lists)

Feature	Description
Usage Count	Shows how many times this category is used in transactions.
Transfer Transactions	Move all transactions from this category to another one before deleting.
Rename	Modify the category name.
Delete	Remove the category (disabled if in use).

Data Management

Export: Download a full JSON backup of your data.
Restore: Restore your data from a backup file.
Import CSV: Bulk import transactions from a CSV file.

Specific Settings

Main Currency: Changing this will recalculate the Base Amount for ALL historical transactions.
AI Provider: Select the AI service provider you want to use.
Passkeys: Login securely without a password using your device (FaceID, TouchID, etc). Note: You must enable 2FA first.