Installation & Setup

Overview

This guide will help you deploy FinanzApp on your own infrastructure. FinanzApp is a PHP-based financial management platform that requires a web server, PHP runtime, and MySQL database.

This project has been archived and is provided as-is under the CC BY-NC 4.0 license. For the latest information, visit the GitHub repository.

System Requirements

Server Requirements

Web Server: Apache 2.4+ or Nginx 1.18+
PHP: 7.4 or higher (8.0+ recommended)
Database: MySQL 5.7+ or MariaDB 10.3+
Memory: Minimum 512MB RAM (1GB+ recommended)
Storage: At least 500MB free disk space

Required PHP Extensions

php-mysqli
php-json
php-session
php-mbstring
php-curl

Optional but Recommended

SSL certificate (Let’s Encrypt recommended)
PHP OPcache for better performance
Redis or Memcached for session storage

FinanzApp uses server-side sessions for authentication. Ensure your PHP installation has session support enabled.

Installation Methods

Manual Installation
Docker Installation

Clone the Repository

Clone the FinanzApp repository to your web server:

cd /var/www/html
git clone https://github.com/Ballwictb/FinanzApp.git finanzapp
cd finanzapp

Set appropriate permissions:

chown -R www-data:www-data /var/www/html/finanzapp
chmod -R 755 /var/www/html/finanzapp

Configure Database

Create a MySQL database and user for FinanzApp:

CREATE DATABASE finanzapp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'finanzapp_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON finanzapp.* TO 'finanzapp_user'@'localhost';
FLUSH PRIVILEGES;

Replace your_secure_password with a strong, unique password. Store this securely as you’ll need it for configuration.

Database Schema

The application requires a users table at minimum. Based on the authentication flow in app/auth/deleteAccount.php:21-24, create the users table:

CREATE TABLE users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL UNIQUE,
    password VARCHAR(255) NOT NULL,
    url_image VARCHAR(500),
    accept_news TINYINT(1) DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

The schema above is inferred from the application code. You may need additional tables for goals, investments, and transactions based on your feature requirements.

Configure the Application

Create a database configuration file. While the codebase references config/database.php (from app/auth/deleteAccount.php:19), you’ll need to create this file:

<?php
// config/database.php

// Database connection parameters
$db_host = 'localhost';
$db_name = 'finanzapp';
$db_user = 'finanzapp_user';
$db_pass = 'your_secure_password';

// Create connection
$conn = new mysqli($db_host, $db_user, $db_pass, $db_name);

// Check connection
if ($conn->connect_error) {
    error_log("Database connection failed: " . $conn->connect_error);
    die("Database connection failed. Please check your configuration.");
}

// Set charset to utf8mb4
$conn->set_charset("utf8mb4");

// Set timezone
$conn->query("SET time_zone = '+00:00'");

Environment Configuration

The base URL is automatically detected in config/config.php:3-10:

<?php
$host = $_SERVER['HTTP_HOST'] ?? '';

// Detect environment automatically
if ($host === 'localhost') {
    define('BASE_URL', '/FinanzApp'); // Localhost with folder
} else {
    define('BASE_URL', ''); // Production on root domain
}

Adjust the localhost path if your installation directory differs.

Configure API Keys

Google reCAPTCHA v3

FinanzApp uses reCAPTCHA for security. Register your site at google.com/recaptcha:

Choose reCAPTCHA v3
Add your domain(s)
Get your Site Key and Secret Key

Update the site key in app/login.php:134:

<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY_HERE"></div>

The current key 6LdpGAErAAAAABtf_pOcsJbRBnytt5t8_WahFXAY is for the original FinanzApp deployment. You must obtain your own keys for your domain.

Google OAuth (Optional)

For Google Sign-In functionality, configure OAuth 2.0:

Go to Google Cloud Console
Create a new project or select existing
Enable Google+ API
Create OAuth 2.0 credentials
Add authorized redirect URIs

Update the client ID in app/register.php:102:

<div id="g_id_onload"
    data-client_id="YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com"
    data-context="signup"
    data-ux_mode="redirect"
    data-login_uri="https://yourdomain.com/app/auth/google-callback.php"
    data-auto_prompt="false">
</div>

EmailJS Configuration

For email notifications, sign up at emailjs.com:

Create an account
Add an email service (Gmail, Outlook, etc.)
Create an email template
Get your Service ID, Template ID, and Public Key

The EmailJS initialization is in js/initEmail.js (obfuscated). You’ll need to update with your credentials:

// js/initEmail.js
emailjs.init('YOUR_PUBLIC_KEY');

And configure the email sending in js/email.js:

const serviceID = 'YOUR_SERVICE_ID';
const templateID = 'YOUR_TEMPLATE_ID';

emailjs.send(serviceID, templateID, {
    to_name: recipientName,
    from_name: 'FinanzApp',
    message: messageContent
});

Configure Web Server

Apache Configuration

Create a virtual host configuration:

<VirtualHost *:80>
    ServerName finanzapp.yourdomain.com
    DocumentRoot /var/www/html/finanzapp
    
    <Directory /var/www/html/finanzapp>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    
    # PHP Configuration
    php_value upload_max_filesize 10M
    php_value post_max_size 10M
    php_value max_execution_time 300
    php_value session.cookie_httponly 1
    php_value session.cookie_secure 1
    
    ErrorLog ${APACHE_LOG_DIR}/finanzapp-error.log
    CustomLog ${APACHE_LOG_DIR}/finanzapp-access.log combined
</VirtualHost>

Enable required Apache modules:

sudo a2enmod rewrite
sudo a2enmod headers
sudo a2enmod ssl
sudo systemctl restart apache2

Nginx Configuration

Alternatively, for Nginx:

server {
    listen 80;
    server_name finanzapp.yourdomain.com;
    root /var/www/html/finanzapp;
    index index.php index.html;
    
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    location ~ /\.ht {
        deny all;
    }
    
    # Cache static assets
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Test and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

SSL Certificate (Recommended)

Secure your installation with Let’s Encrypt:

sudo apt install certbot python3-certbot-apache  # For Apache
# OR
sudo apt install certbot python3-certbot-nginx   # For Nginx

# Obtain certificate
sudo certbot --apache -d finanzapp.yourdomain.com
# OR
sudo certbot --nginx -d finanzapp.yourdomain.com

Certbot will automatically configure SSL and set up auto-renewal.

Always use HTTPS in production. FinanzApp handles sensitive financial data and requires secure connections.

Test the Installation

Verify your installation:

Check PHP Info: Create a temporary file info.php in your web root:
```
<?php phpinfo(); ?>
```
Visit https://finanzapp.yourdomain.com/info.php and verify PHP version and extensions. Delete this file after verification!

Test Database Connection: Create test-db.php:

<?php
require_once 'config/database.php';
if ($conn->ping()) {
    echo "Database connection successful!";
} else {
    echo "Database connection failed: " . $conn->error;
}
$conn->close();

Delete after testing!

Test Registration: Navigate to /app/register.php and create a test account
Test Login: Visit /app/login.php and log in with your test credentials
Verify Session: After login, check that you can access /app/userConfig.php without being redirected

Docker configuration is not provided in the source repository. Below is a suggested setup for containerized deployment.

Docker Compose Configuration

Create a docker-compose.yml file:

version: '3.8'

services:
  web:
    image: php:8.0-apache
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./:/var/www/html
      - ./docker/apache/finanzapp.conf:/etc/apache2/sites-available/000-default.conf
    depends_on:
      - db
    environment:
      - APACHE_DOCUMENT_ROOT=/var/www/html
    networks:
      - finanzapp-network

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: finanzapp
      MYSQL_USER: finanzapp_user
      MYSQL_PASSWORD: secure_password
    volumes:
      - db-data:/var/lib/mysql
      - ./docker/mysql/init.sql:/docker-entrypoint-initdb.d/init.sql
    networks:
      - finanzapp-network

  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    ports:
      - "8080:80"
    environment:
      PMA_HOST: db
      MYSQL_ROOT_PASSWORD: root_password
    depends_on:
      - db
    networks:
      - finanzapp-network

volumes:
  db-data:

networks:
  finanzapp-network:
    driver: bridge

Deploy with:

docker-compose up -d

Post-Installation Configuration

Language Configuration

FinanzApp supports three languages out of the box. Language files are located in langs/ directory:

es.json - Spanish (default)
en.json - English
fr.json - French

The language detection system in config/config.php:17-31 automatically:

Checks URL parameter (?lang=en)
Falls back to session value
Defaults to Spanish

You can modify the default language by changing:

$lang = $_GET['lang'] ?? $_SESSION['lang'] ?? 'en'; // Changed default to English

Security Hardening

Secure PHP Configuration

Edit your php.ini:

; Disable dangerous functions
disable_functions = exec,passthru,shell_exec,system,proc_open,popen

; Hide PHP version
expose_php = Off

; Session security
session.cookie_httponly = 1
session.cookie_secure = 1
session.cookie_samesite = Strict
session.use_strict_mode = 1

; File upload limits
upload_max_filesize = 5M
post_max_size = 6M

; Error handling
display_errors = Off
log_errors = On
error_log = /var/log/php/error.log

File Permissions

Set restrictive permissions:

# Set owner
chown -R www-data:www-data /var/www/html/finanzapp

# Directories: 755, Files: 644
find /var/www/html/finanzapp -type d -exec chmod 755 {} \;
find /var/www/html/finanzapp -type f -exec chmod 644 {} \;

# Protect sensitive files
chmod 600 /var/www/html/finanzapp/config/database.php

Database Security

Secure your MySQL installation:

# Run security script
mysql_secure_installation

Restrict database user privileges:

-- Revoke unnecessary privileges
REVOKE ALL PRIVILEGES ON *.* FROM 'finanzapp_user'@'localhost';

-- Grant only required privileges
GRANT SELECT, INSERT, UPDATE, DELETE ON finanzapp.* TO 'finanzapp_user'@'localhost';
FLUSH PRIVILEGES;

Backup Strategy

Implement regular backups:

#!/bin/bash
# backup-finanzapp.sh

# Configuration
BACKUP_DIR="/backups/finanzapp"
DATE=$(date +%Y%m%d_%H%M%S)
DB_NAME="finanzapp"
DB_USER="finanzapp_user"
DB_PASS="your_secure_password"

# Create backup directory
mkdir -p $BACKUP_DIR

# Backup database
mysqldump -u$DB_USER -p$DB_PASS $DB_NAME | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# Backup files
tar -czf $BACKUP_DIR/files_$DATE.tar.gz /var/www/html/finanzapp

# Keep only last 30 days
find $BACKUP_DIR -name "*.gz" -mtime +30 -delete

echo "Backup completed: $DATE"

Schedule with cron:

# Daily backup at 2 AM
0 2 * * * /usr/local/bin/backup-finanzapp.sh

Performance Optimization

Enable OPcache

Add to php.ini:

opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.revalidate_freq=60

Database Indexing

Optimize frequently queried columns:

-- Add indexes for better performance
CREATE INDEX idx_created_at ON users(created_at);
CREATE INDEX idx_email_password ON users(email, password);

CDN for Static Assets

FinanzApp uses CDN resources for libraries. Ensure they’re accessible:

<!-- Chart.js from CDN (index.php:175) -->
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>

<!-- Notyf notifications (index.php:176) -->
<script src="https://cdn.jsdelivr.net/npm/notyf/notyf.min.js"></script>

<!-- Font Awesome icons (index.php:42) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Ballwictb/font-awesome-sixball-v2@main/six-rp/css/all.min.css">

Monitoring and Maintenance

Log Monitoring

Regularly check logs:

# Apache/Nginx error logs
tail -f /var/log/apache2/finanzapp-error.log
tail -f /var/log/nginx/error.log

# PHP error logs
tail -f /var/log/php/error.log

# MySQL logs
tail -f /var/log/mysql/error.log

Health Checks

Create a health check endpoint:

<?php
// health-check.php
header('Content-Type: application/json');

$health = [
    'status' => 'ok',
    'timestamp' => time(),
    'checks' => []
];

// Check database
try {
    require_once 'config/database.php';
    $health['checks']['database'] = $conn->ping() ? 'ok' : 'error';
    $conn->close();
} catch (Exception $e) {
    $health['checks']['database'] = 'error';
    $health['status'] = 'error';
}

// Check session support
$health['checks']['session'] = session_status() !== PHP_SESSION_DISABLED ? 'ok' : 'error';

// Check required extensions
$required_extensions = ['mysqli', 'json', 'mbstring', 'curl'];
foreach ($required_extensions as $ext) {
    $health['checks']['ext_' . $ext] = extension_loaded($ext) ? 'ok' : 'error';
    if (!extension_loaded($ext)) {
        $health['status'] = 'error';
    }
}

http_response_code($health['status'] === 'ok' ? 200 : 503);
echo json_encode($health, JSON_PRETTY_PRINT);

Troubleshooting

Common Issues

Session errors or login not working

Symptoms: Users can’t log in or sessions expire immediatelySolutions:

Verify PHP session directory is writable: ls -la /var/lib/php/sessions
Check session configuration in php.ini
Ensure session cookies are being set (check browser dev tools)
Verify session_start() is called in config/config.php:12-14

Database connection failed

Symptoms: “Database connection failed” error messageSolutions:

Verify MySQL is running: systemctl status mysql
Check credentials in config/database.php
Test connection with MySQL client: mysql -u finanzapp_user -p finanzapp
Check MySQL error logs: tail -f /var/log/mysql/error.log
Verify the user has correct permissions

reCAPTCHA validation fails

Symptoms: Registration or login fails with reCAPTCHA errorsSolutions:

Ensure you’re using your own reCAPTCHA keys, not the demo keys
Verify domain is registered in Google reCAPTCHA console
Check that js/api.js is loading correctly
Test with a different IP address (rate limiting may apply)

Email notifications not sending

Symptoms: Users don’t receive email notificationsSolutions:

Verify EmailJS credentials are configured correctly
Check browser console for JavaScript errors
Ensure js/initEmail.js and js/email.js are loading
Test EmailJS service independently
Check spam folder for test emails

Google Sign-In not working

Static assets not loading

Symptoms: Missing styles, broken images, or JavaScript errorsSolutions:

Check BASE_URL configuration in config/config.php
Verify file permissions allow web server to read assets
Check browser console for 404 errors
Ensure CDN resources are accessible (not blocked by firewall)

Debug Mode

For development, enable detailed error reporting:

<?php
// Add to top of config/config.php for debugging only
if ($_SERVER['HTTP_HOST'] === 'localhost') {
    ini_set('display_errors', 1);
    ini_set('display_startup_errors', 1);
    error_reporting(E_ALL);
}

Never enable display_errors in production! Always log errors to files instead.

Upgrading

To upgrade to a newer version:

# Backup current installation
cp -r /var/www/html/finanzapp /var/www/html/finanzapp.backup
mysqldump -u finanzapp_user -p finanzapp > finanzapp_backup.sql

# Pull latest changes
cd /var/www/html/finanzapp
git fetch origin
git pull origin main

# Clear PHP OPcache
sudo systemctl restart php8.0-fpm  # or apache2

Support and Resources

GitHub Repository

Source code, issues, and pull requests

Live Demo

Try FinanzApp before installing

Security Policy

Report security vulnerabilities

Contributing

Contribution guidelines

Next Steps

After installation:

Read the Quickstart Guide to understand user workflows
Set up automated backups
Configure monitoring and alerting
Review security settings
Test all features thoroughly

This project was developed as a Final Year Project at IES La Arboleda. It is licensed under CC BY-NC 4.0 and provided as-is without warranty.

Getting Started

Core Features

User Guide

Security

​Overview

​System Requirements

​Server Requirements

​Required PHP Extensions

​Optional but Recommended

​Installation Methods

​Database Schema

​Environment Configuration

​Google reCAPTCHA v3

​Google OAuth (Optional)

​EmailJS Configuration

​Apache Configuration

​Nginx Configuration

​Docker Compose Configuration

​Post-Installation Configuration

​Language Configuration

​Security Hardening

​Backup Strategy

​Performance Optimization

​Enable OPcache

​Database Indexing

​CDN for Static Assets

​Monitoring and Maintenance

​Log Monitoring

​Health Checks

​Troubleshooting

​Common Issues

​Debug Mode

​Upgrading

​Support and Resources

GitHub Repository

Live Demo

Security Policy

Contributing

​Next Steps

Build docs developers (and LLMs) love

Overview

System Requirements

Server Requirements

Required PHP Extensions

Optional but Recommended

Installation Methods

Database Schema

Environment Configuration

Google reCAPTCHA v3

Google OAuth (Optional)

EmailJS Configuration

Apache Configuration

Nginx Configuration

Docker Compose Configuration

Post-Installation Configuration

Language Configuration

Security Hardening

Backup Strategy

Performance Optimization

Enable OPcache

Database Indexing

CDN for Static Assets

Monitoring and Maintenance

Log Monitoring

Health Checks

Troubleshooting

Common Issues

Debug Mode

Upgrading

Support and Resources

Next Steps