Self-Hosting Installation
This guide covers deploying Home Account on your own infrastructure. The recommended setup uses:- Frontend: Vercel (Next.js App Router)
- Backend: Render (Express API)
- Database: Aiven (Managed MySQL)
Architecture Overview
Prerequisites
Before you begin, ensure you have:- Git: For cloning the repository
- Node.js: v18 or higher
- pnpm: v10.13.1 or compatible (or npm/yarn)
- MySQL: v8.0 or higher (or Aiven account)
- Vercel Account: For frontend deployment (or alternative)
- Render Account: For backend deployment (or alternative)
- EmailJS Account: For password reset emails (optional but recommended)
- OAuth Credentials: Google and/or GitHub (optional)
- AI Provider Keys: Groq, Ollama, Claude, or Gemini (optional)
Step 1: Clone the Repository
Step 2: Database Setup (MySQL)
- Aiven (Managed)
- Self-Hosted MySQL
Create Aiven MySQL Instance
Sign Up for Aiven
Go to aiven.io and create a free account. The free tier includes a MySQL instance suitable for development.
Create MySQL Service
- Click Create Service
- Select MySQL as the service type
- Choose a cloud provider and region (closest to your backend)
- Select Startup-4 plan (free tier) for testing
- Name your service (e.g.,
home-account-db) - Click Create Service
Wait for Provisioning
The database takes 5-10 minutes to provision. Wait for status to show Running.
Get Connection Details
Click on your service and navigate to Overview:
- Host:
mysql-xxxxxx.aivencloud.com - Port:
25060(default) - Username:
avnadmin - Password: Auto-generated, click to reveal
- Database: Create one named
home_account
Create Database Schema
Home Account requires tables for users, accounts, transactions, categories, etc.Database migrations are not included in the repository. You’ll need to infer the schema from the TypeScript models or request the SQL schema file from the maintainers.
Step 3: Backend Configuration
Configure OAuth (Optional)
Google OAuth
- Go to Google Cloud Console
- Create a new project or select existing
- Enable Google+ API
- Create OAuth 2.0 Client ID
- Application type: Web application
- Authorized redirect URIs:
http://localhost:3001/api/auth/google/callback(dev) andhttps://your-backend.onrender.com/api/auth/google/callback(prod)
- Copy Client ID and Client Secret
GitHub OAuth
- Go to GitHub Developer Settings
- Click New OAuth App
- Fill details:
- Application name: Home Account
- Homepage URL:
http://localhost:3000 - Authorization callback URL:
http://localhost:3001/api/auth/github/callback
- Copy Client ID and generate Client Secret
Configure EmailJS (Optional)
For password reset emails:
- Sign up at EmailJS
- Create an email service (Gmail, Outlook, etc.)
- Create a template for password reset with variables:
{{to_email}},{{reset_link}},{{user_name}} - Get credentials from Account page
Complete .env File Example
Step 4: Frontend Configuration
Configure API URL
Edit
.env.local:NEXT_PUBLIC_API_URL: Used by client-side code (exposed to browser)API_URL: Used by Server Components (not exposed)
Step 5: Local Development Testing
Test Registration
- Open browser to
http://localhost:3000 - Click Register
- Create an account
- Verify you can login and see the dashboard
Step 6: Deploy Backend to Render
Create Render Account
Sign up at render.com (free tier available).
Create New Web Service
- Click New + → Web Service
- Connect your GitHub repository (fork Home Account first)
- Configure:
- Name:
home-account-api - Region: Choose closest to your users
- Branch:
main - Root Directory:
backend - Runtime: Node
- Build Command:
pnpm install - Start Command:
pnpm start - Instance Type: Free (for testing) or Starter ($7/mo)
- Name:
Set Environment Variables
In Render dashboard, go to Environment and add all variables from your
.env:Deploy
Click Create Web Service. Render will:
- Clone your repository
- Run
pnpm install - Start with
pnpm start(which runstsx index.ts) - Assign a URL like
https://home-account-api.onrender.com
Render Free Tier: Services spin down after 15 minutes of inactivity. First request after spin-down takes 30-60 seconds. Use paid Starter plan for always-on instances.
Step 7: Deploy Frontend to Vercel
Create Vercel Account
Sign up at vercel.com (free for personal projects).
Import Project
- Click New Project
- Import your GitHub repository (fork first)
- Vercel auto-detects Next.js configuration
Configure Build Settings
- Framework Preset: Next.js
- Root Directory:
frontend - Build Command:
pnpm build(auto-detected) - Output Directory:
.next(auto-detected) - Install Command:
pnpm install(auto-detected)
Deploy
Click Deploy. Vercel will:
- Build your Next.js app
- Deploy to global CDN
- Assign a URL like
https://home-account-xxxx.vercel.app
Update Backend CORS
Go back to Render backend environment variables and update:Restart the backend service.
Step 8: Configure Custom Domain (Optional)
- Vercel Domain
- Render Domain
Add Custom Domain to Vercel
Step 9: Production Checklist
Before launching to production users:- Database Backups: Set up automated backups in Aiven (or your provider)
- Environment Variables: Double-check all secrets are set correctly
- SSL Certificates: Verify HTTPS works on all domains
- CORS Configuration: Test that frontend can reach backend
- OAuth Redirects: Confirm Google/GitHub login works with production URLs
- Email Delivery: Test password reset emails are delivered
- Rate Limiting: Verify rate limits are active on login and imports
- Error Monitoring: Set up Sentry or similar (optional)
- Analytics: Configure Vercel Analytics (optional)
- Performance: Test with production data volume
- Security Headers: Verify CSP and other headers are set
- Recovery Flow: Test BIP39 recovery and password reset
Maintenance
Regular Tasks
- Database Backups: Weekly or daily (automated in Aiven)
- Dependency Updates: Monthly
pnpm updateand test - Security Patches: Monitor GitHub Dependabot alerts
- Log Monitoring: Check Render logs for errors
- SSL Renewal: Automatic with Let’s Encrypt (verify every 3 months)
Monitoring
Troubleshooting
Backend won’t start
- Check Render logs for errors
- Verify all environment variables are set
- Test database connection manually:
Frontend can’t reach backend
- Check CORS configuration in backend
.env - Verify
FRONTEND_URLmatches your Vercel domain - Test backend health endpoint directly
- Check browser console for CORS errors
Database connection fails
- Verify MySQL service is running (Aiven dashboard)
- Check firewall rules allow connections from Render IPs
- Confirm credentials are correct
- Test connection with MySQL client
OAuth login fails
- Verify OAuth redirect URIs match production URLs
- Check OAuth credentials are correct in backend
.env - Test OAuth callback endpoint directly
- Review backend logs for OAuth errors
Advanced Configuration
AI Provider Setup
For investment features, configure AI providers:- Groq (Recommended)
- Ollama (Local)
- Claude
- Gemini
PWA Configuration
The frontend is already configured as a PWA with Serwist. Users can install it from their browser. To customize the PWA manifest:Security Hardening
For production deployments, consider:- Rate Limiting: Adjust limits in
backend/middlewares/rateLimiter.ts - IP Allowlisting: Restrict database access to backend IPs only
- Secrets Rotation: Rotate JWT secret and OAuth secrets periodically
- Audit Logs: Add logging for sensitive operations (logins, password changes)
- 2FA: Implement TOTP two-factor authentication (not included)
- Penetration Testing: Hire security professionals to audit
Next Steps
Quickstart Guide
Learn how to use Home Account as an end user
API Reference
Explore the backend API endpoints
Contributing
Contribute to the Home Account project
Architecture Deep Dive
Understand the technical design decisions
