Installation Guide

This comprehensive guide will walk you through installing Cashify on your local development environment. Follow these steps to get Cashify up and running in minutes.

System Requirements

Before you begin, ensure your system meets these requirements:

Backend Requirements

PHP: 8.2 or higher
Composer: Latest version
SQLite: 3.x (or MySQL/PostgreSQL)
PHP Extensions: PDO, OpenSSL, Mbstring, Tokenizer, XML, Ctype, JSON

Frontend Requirements

Node.js: 18.x or higher
npm: 9.x or higher (or yarn/pnpm)
Modern Browser: Chrome, Firefox, Safari, or Edge

Cashify uses SQLite by default for easy setup and portability. For production deployments, consider using PostgreSQL or MySQL.

Installation Steps

Follow these steps to install Cashify on your local machine:

Clone the Repository

First, clone the Cashify repository from GitHub:

git clone https://github.com/yyordan0v/cashify.git

This will create a cashify directory with all the source code.

Navigate to Project Directory

Change into the project directory:

cd cashify

Install PHP Dependencies

Use Composer to install all backend dependencies:

composer install

This installs packages including:

Laravel Framework (^11.0)
Laravel Breeze (^2.0) for authentication
Laravel Socialite (^5.15) for GitHub OAuth
Laravel HTMX (^0.6.0) for dynamic interactions

{
  "require": {
    "php": "^8.2",
    "laravel/framework": "^11.0",
    "laravel/breeze": "^2.0",
    "laravel/socialite": "^5.15",
    "laravel/telescope": "^5.1",
    "mauricius/laravel-htmx": "^0.6.0"
  }
}

Install JavaScript Dependencies

Install frontend dependencies using npm:

npm install

This installs:

Alpine.js (^3.4.2) for reactive components
Tailwind CSS (^3.1.0) for styling
ApexCharts (^3.49.1) for data visualization
Vite (^5.0) for asset bundling

{
  "dependencies": {
    "apexcharts": "^3.49.1"
  },
  "devDependencies": {
    "@tailwindcss/forms": "^0.5.2",
    "alpinejs": "^3.4.2",
    "autoprefixer": "^10.4.2",
    "laravel-vite-plugin": "^1.0",
    "tailwindcss": "^3.1.0",
    "vite": "^5.0"
  }
}

Configure Environment Variables

Copy the example environment file and customize it for your setup:

cp .env.example .env

The .env file contains important configuration options:

# SQLite (Default)
DB_CONNECTION=sqlite

# Or MySQL/PostgreSQL
# DB_CONNECTION=mysql
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=cashify
# DB_USERNAME=root
# DB_PASSWORD=

Generate Application Key

Generate a unique application encryption key:

php artisan key:generate

This command generates a random key and automatically adds it to your .env file:

APP_KEY=base64:generated_key_here

Never commit your .env file or share your APP_KEY. This key is used for encrypting sensitive data.

Create Database

If using SQLite (default), create the database file:

touch database/database.sqlite

For MySQL or PostgreSQL, create the database using your database management tool:

CREATE DATABASE cashify CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Run Database Migrations

Execute migrations to create all necessary database tables:

php artisan migrate

This creates the following tables:

users - User accounts and authentication
accounts - Financial accounts (checking, savings, etc.)
categories - Transaction categories
transactions - Financial transactions
net_worths - Net worth tracking data
sessions - User session data
cache - Application cache
jobs - Queue jobs

Schema::create('accounts', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('name');
    $table->decimal('balance', 15, 2)->default(0);
    $table->string('color');
    $table->timestamps();
});

Compile Frontend Assets

Build the frontend assets using Vite:For Development:

npm run dev

This starts the Vite development server with hot module replacement (HMR) for real-time updates during development.For Production:

npm run build

This creates optimized, minified assets in the public/build directory.

Start the Development Server

Launch the Laravel development server:

php artisan serve

The application will be available at http://localhost:8000

Keep this terminal window open. The server must be running to access the application.

Accessing the Application

Once installation is complete:

Open Your Browser

Navigate to http://localhost:8000

Create an Account

Click “Register” to create a new user account, or “Login with GitHub” if you’ve configured GitHub OAuth

# Routes for authentication (defined in routes/auth.php)
GET  /register           # Registration form
POST /register           # Create new account
GET  /login              # Login form
POST /login              # Authenticate user
GET  /auth/github        # GitHub OAuth redirect
GET  /auth/github/callback  # GitHub OAuth callback

Access the Dashboard

After authentication, you’ll be redirected to the dashboard at /dashboard

Optional: GitHub OAuth Setup

To enable GitHub authentication:

Create GitHub OAuth App

Go to GitHub Settings → Developer settings → OAuth Apps
Click “New OAuth App”
Fill in the application details:
- Application name: Cashify (or your preferred name)
- Homepage URL: http://localhost:8000
- Authorization callback URL: http://localhost:8000/auth/github/callback

Get Credentials

After creating the app, GitHub will provide:

Client ID
Client Secret

Update Environment Variables

Add the credentials to your .env file:

GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_REDIRECT=http://localhost:8000/auth/github/callback

Test Authentication

Visit the login page and click “Login with GitHub” to test the OAuth flow

Never commit your GitHub OAuth credentials to version control. Keep them secure in your .env file.

Development Workflow

Running in Development Mode

For active development, you’ll want to run both servers simultaneously:

# Terminal 1: Laravel development server
php artisan serve

# Terminal 2: Vite development server (with HMR)
npm run dev

This setup provides:

Hot module replacement for instant CSS/JS updates
Automatic browser refresh on file changes
Source maps for easier debugging

Useful Artisan Commands

Database Commands

# Run migrations
php artisan migrate

# Rollback last migration
php artisan migrate:rollback

# Reset database and re-run all migrations
php artisan migrate:fresh

# Check migration status
php artisan migrate:status

Cache Commands

# Clear application cache
php artisan cache:clear

# Clear configuration cache
php artisan config:clear

# Clear route cache
php artisan route:clear

# Clear view cache
php artisan view:clear

# Clear all caches
php artisan optimize:clear

Development Tools

# Start Laravel Telescope (debugging)
# Available at /telescope
php artisan telescope:install

# Run tests
php artisan test

# Or with Pest
./vendor/bin/pest

# Code formatting with Laravel Pint
./vendor/bin/pint

Troubleshooting

Composer Install Fails

Issue: Composer dependencies won’t installSolutions:

Ensure PHP 8.2+ is installed: php -v
Check required PHP extensions: php -m
Update Composer: composer self-update
Clear Composer cache: composer clear-cache

NPM Install Errors

Issue: Node packages fail to installSolutions:

Update Node.js to version 18+: node -v
Clear npm cache: npm cache clean --force
Delete node_modules and package-lock.json, then run npm install again
Try using yarn or pnpm instead

Migration Errors

Issue: Database migrations failSolutions:

Verify database connection in .env
For SQLite, ensure database/database.sqlite exists
Check database user permissions
Review migration error messages for specific issues
Try: php artisan migrate:fresh (Warning: deletes all data)

Assets Not Loading

Issue: CSS/JS files return 404 errorsSolutions:

Ensure Vite is running: npm run dev
Check APP_URL in .env matches your browser URL
Clear browser cache
Verify public/build directory exists (after npm run build)
Check file permissions on public directory

Permission Denied Errors

Issue: File permission errors during installationSolutions:

# Make storage and cache directories writable
chmod -R 775 storage bootstrap/cache

# If using Apache/Nginx, set correct ownership
sudo chown -R www-data:www-data storage bootstrap/cache

Port 8000 Already in Use

Issue: Can’t start server because port 8000 is busySolutions:

# Use a different port
php artisan serve --port=8001

# Or kill the process using port 8000
# On Linux/Mac:
lsof -ti:8000 | xargs kill -9

# On Windows:
netstat -ano | findstr :8000
taskkill /PID <PID> /F

Production Deployment

For production deployment, additional steps are recommended:

These instructions are for production environments. Do not use these settings in development.

Environment Configuration

Update your .env for production:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Use a production database
DB_CONNECTION=mysql
DB_HOST=your_database_host
DB_DATABASE=cashify_production
DB_USERNAME=your_db_user
DB_PASSWORD=your_secure_password

Build Assets

npm run build

This creates optimized, minified production assets.

Optimize Laravel

# Cache configuration
php artisan config:cache

# Cache routes
php artisan route:cache

# Cache views
php artisan view:cache

# Optimize autoloader
composer install --optimize-autoloader --no-dev

Set Permissions

chmod -R 755 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Configure Web Server

Point your web server (Apache/Nginx) to the public directory:Nginx Example:

server {
    listen 80;
    server_name yourdomain.com;
    root /path/to/cashify/public;
    
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
    
    index index.php;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Setup SSL

Use Let’s Encrypt for free SSL certificates:

sudo certbot --nginx -d yourdomain.com

Schedule Jobs (Optional)

If using scheduled tasks, add to crontab:

* * * * * cd /path/to/cashify && php artisan schedule:run >> /dev/null 2>&1

Next Steps

Now that Cashify is installed:

Quickstart Guide

Learn how to create your first account and transaction

Demo Video

Watch a full demonstration of Cashify’s features

GitHub Repository

View source code, report issues, or contribute

Laravel Documentation

Learn more about the Laravel framework

Getting Help

If you encounter issues during installation:

Check Error Messages: Read error output carefully for specific issues
Review Logs: Check storage/logs/laravel.log for application errors
GitHub Issues: Search existing issues or create a new one
Laravel Documentation: Official Laravel docs for framework-specific questions

Welcome to Cashify! Start taking control of your finances today.

Get Started

Core Features

Configuration

Development

Deployment

Installation Guide

Installation Guide

System Requirements

Backend Requirements

Frontend Requirements

Installation Steps

Accessing the Application

Optional: GitHub OAuth Setup

Development Workflow

Running in Development Mode

Useful Artisan Commands

Troubleshooting

Production Deployment

Next Steps

Quickstart Guide

Demo Video

GitHub Repository

Laravel Documentation

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Development

Deployment

​Installation Guide

​System Requirements

Backend Requirements

Frontend Requirements

​Installation Steps

​Accessing the Application

​Optional: GitHub OAuth Setup

​Development Workflow

​Running in Development Mode

​Useful Artisan Commands

​Troubleshooting

​Production Deployment

​Next Steps

Quickstart Guide

Demo Video

GitHub Repository

Laravel Documentation

​Getting Help

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Installation Steps

Accessing the Application

Optional: GitHub OAuth Setup

Development Workflow

Running in Development Mode

Useful Artisan Commands

Troubleshooting

Production Deployment

Next Steps

Getting Help