How To Install Actual Budget on Ubuntu 24.04 LTS

Actual Budget offers a refreshing approach to managing personal finances through its open-source platform that prioritizes user privacy and data control. Unlike cloud-based alternatives, this envelope-style budgeting software puts you in complete control of your financial data while providing powerful tools to track income, expenses, and overall financial health. This comprehensive guide walks you through the installation process on Ubuntu 24.04 LTS, covering everything from basic setup to advanced configuration options.

Understanding Actual Budget

Actual Budget stands out in the crowded personal finance software market with its commitment to privacy and user control. At its core, the application leverages the time-tested envelope budgeting methodology, which helps users allocate income to specific spending categories before the money is actually spent. This proactive approach to money management encourages mindful spending and prevents overspending.

The software is designed with a “local-first” philosophy, meaning your financial data remains on your device rather than being stored in the cloud. This approach significantly enhances privacy while still offering modern conveniences through its optional synchronization capabilities. The multi-device sync functionality allows you to access your budgets across different devices without compromising on data security.

Key Features and Benefits:

• Complete ownership and control of your financial data
• Envelope-style budgeting system based on actual income
• Multi-device synchronization with optional end-to-end encryption
• Offline functionality that doesn’t rely on constant internet connection
• Support for importing transactions from popular financial file formats
• Robust reporting capabilities for analyzing spending patterns
• Bank syncing capabilities through third-party services

Prerequisites for Installation

Before diving into the installation process, ensure your system meets the necessary requirements for a smooth setup experience. The following elements are essential for installing Actual Budget on Ubuntu 24.04 LTS:

• Ubuntu 24.04 LTS with current updates applied
• User account with sudo privileges for administrative tasks
• Minimum 2GB RAM and 4GB of free disk space
• Active internet connection for downloading packages
• Basic familiarity with terminal commands and Linux operations
• Node.js version 18 or above (will be installed during this guide)
• Domain name (optional, only required for remote access setup)

This guide assumes you’re starting with a fresh Ubuntu 24.04 LTS installation or one that doesn’t have the required dependencies yet installed. The entire installation process typically takes 15-30 minutes, depending on your system’s performance and internet connection speed.

Preparing Your Ubuntu System

The first step toward a successful Actual Budget installation involves preparing your Ubuntu system with the necessary updates and configurations. This foundation ensures compatibility and optimal performance once the application is installed.

Start by opening a terminal window and updating your system packages:

sudo apt update
sudo apt upgrade -y

This command refreshes your package lists and upgrades all installed packages to their latest versions. The -y flag automatically confirms the upgrade process to save time.

Next, create a dedicated directory structure for the Actual Budget installation:

mkdir -p ~/applications/actual-budget
cd ~/applications/actual-budget

Organizing your installation in a dedicated directory makes maintenance and troubleshooting easier in the future. This structured approach also simplifies backup procedures and potential migrations.

Installing Node.js

Actual Budget is built on Node.js, making this runtime environment essential for running the application. Ubuntu 24.04 LTS allows for a straightforward installation of Node.js through the official repositories.

Execute the following commands to install Node.js and npm (Node Package Manager):

sudo apt update
sudo apt install nodejs npm git -y

After installation completes, verify that Node.js and npm are properly installed by checking their versions:

node --version
npm --version

Actual Budget requires Node.js version 18 or higher. If your installed version is lower, you might need to use a different installation method, such as the NodeSource repository:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

This alternative method installs the LTS (Long Term Support) version of Node.js, which offers better stability and compatibility for production environments.

Setting Up Git and Yarn

The next components needed for installing Actual Budget are Git for version control and Yarn for package management. These tools facilitate downloading the source code and managing dependencies efficiently.

Install Git if it’s not already installed:

sudo apt install git -y

Next, install Yarn globally using npm:

sudo npm install --global yarn

Verify that both Git and Yarn are correctly installed and accessible:

git --version
yarn --version

Yarn provides several advantages over npm for this installation, including faster dependency resolution and more reliable package installations. These benefits become particularly important when dealing with complex Node.js applications like Actual Budget.

Downloading the Actual Budget Source Code

With all prerequisites in place, you can now proceed to download the Actual Budget source code from its GitHub repository. The application is actively maintained by a community of developers who regularly update and improve its functionality.

Use Git to clone the repository:

git clone https://github.com/actualbudget/actual-server.git

This command creates a new directory named actual-server containing all the necessary files for running Actual Budget. Navigate into this directory to continue with the installation:

cd actual-server

The repository contains both the server component and the client interface needed for running Actual Budget. The server handles data storage and synchronization, while the client provides the user interface for interacting with your financial data.

Installing Dependencies

Once you’ve downloaded the source code, the next step involves installing all the JavaScript dependencies required by Actual Budget. These dependencies provide essential functionality that the application relies on.

Run the following command within the actual-server directory:

yarn install

This process might take several minutes depending on your internet connection and system performance. Yarn will download and install numerous packages specified in the project’s package.json file.

During the installation, you might see some warnings in the terminal—these are generally harmless and can be ignored unless they explicitly indicate errors. The installation is successful when you see a message confirming that all dependencies have been added without fatal errors.

Configuring Actual Budget

After installing dependencies, you need to create a configuration file that specifies how Actual Budget should run on your system. This file determines network settings, data storage locations, and other operational parameters.

Create a new configuration file named config.json in the actual-server directory:

nano config.json

Add the following basic configuration to the file:

{
  "hostname": "127.0.0.1",
  "port": 5006
}

This configuration sets Actual Budget to run on localhost (127.0.0.1) and listen on port 5006. Save the file and exit the editor (Ctrl+O, Enter, Ctrl+X in nano).

For more advanced setups, you can specify additional configuration options such as:

{
  "hostname": "0.0.0.0",
  "port": 5006,
  "dataDir": "/path/to/data/storage",
  "logLevel": "info"
}

Setting the hostname to “0.0.0.0” allows connections from any IP address, which is useful if you want to access the application from other devices on your network. However, this requires additional security measures to prevent unauthorized access.

Manual Testing

Before setting up Actual Budget as a system service, it’s wise to test the application manually to ensure everything works correctly. This step helps identify and resolve any configuration issues early in the installation process.

Start Actual Budget using the following command:

yarn start

You should see output indicating that the server has started successfully and is listening on the configured port. Open a web browser and navigate to:

http://localhost:5006

You should see the Actual Budget welcome screen, which prompts you to create an administrator password. If the page loads correctly, congratulations! Your manual test is successful. You can stop the application by pressing Ctrl+C in the terminal.

If you encounter any issues during this test, check the terminal output for error messages that might indicate the problem. Common issues include port conflicts or missing dependencies.

Creating a Systemd Service

To ensure Actual Budget starts automatically when your system boots and runs in the background, you should create a systemd service. This approach provides better management and reliability than manually starting the application.

Create a new systemd service file:

sudo nano /etc/systemd/system/actual.service

Add the following configuration to the file, replacing username with your actual username:

[Unit]
Description=Actual-Server (https://actualbudget.org)
After=network.target

[Service]
User=username
Group=username
WorkingDirectory=/home/username/applications/actual-budget/actual-server/
ExecStart=/usr/local/bin/yarn start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

This configuration specifies that the service should run as your user, start after the network is available, and automatically restart if it fails. Save and close the file.

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable actual.service
sudo systemctl start actual.service

Verify that the service is running correctly:

sudo systemctl status actual.service

The output should show that the service is active and running. If you see any errors, check the logs for more detailed information:

journalctl -u actual.service

Accessing and Initial Setup

With Actual Budget running as a service, you can now access the application and complete the initial setup. Open your web browser and navigate to:

http://localhost:5006

On the welcome screen, you’ll be prompted to create an administrator password for accessing your financial data. Choose a strong, unique password that you can remember but would be difficult for others to guess.

After setting the password, you’ll be presented with options to create a new budget or import an existing one. If you’re new to Actual Budget, creating a fresh budget allows you to start from scratch. Alternatively, if you’re migrating from another financial application, you might prefer to import your existing data.

The application offers several import options, including:

• YNAB4 and nYNAB importers
• QIF, OFX, QFX, CAMT.053, and CSV file imports
• Manual transaction entry

During the initial setup, take time to explore the interface and understand the envelope budgeting methodology if you’re new to this approach. The system is designed to be intuitive, but familiarity with the concepts helps maximize its benefits.

Setting Up Nginx as a Reverse Proxy (Optional)

For enhanced security and flexibility, you might want to set up Nginx as a reverse proxy for Actual Budget. This configuration allows you to access the application through a standard web port and potentially add SSL encryption.

Install Nginx:

sudo apt install nginx -y

Create a new server block configuration:

sudo nano /etc/nginx/sites-available/actual

Add the following configuration, adjusting as needed:

server {
    listen 80;
    server_name budget.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:5006;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

This configuration forwards requests to your Actual Budget instance running on localhost:5006. Save and close the file.

Enable the configuration and restart Nginx:

sudo ln -s /etc/nginx/sites-available/actual /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

If you have a domain name pointed to your server, you can now access Actual Budget through that domain (http://budget.yourdomain.com in this example).

Implementing HTTPS Security (Optional)

Securing your Actual Budget installation with HTTPS is highly recommended, especially if you plan to access it remotely. Let’s Encrypt provides free SSL certificates that are easy to implement with Certbot.

Install Certbot:

sudo apt install certbot python3-certbot-nginx -y

Obtain an SSL certificate:

sudo certbot --nginx -d budget.yourdomain.com

Follow the prompts to complete the certificate issuance process. Certbot will automatically modify your Nginx configuration to use the new certificate and redirect HTTP traffic to HTTPS.

Test the automatic renewal process:

sudo certbot renew --dry-run

Let’s Encrypt certificates are valid for 90 days, but Certbot sets up a systemd timer to automatically renew certificates before they expire.

Updating Actual Budget

Keeping Actual Budget updated ensures you have access to the latest features and security improvements. The application receives regular updates from its active development community.

To update your installation:

1. Back up your data first (export your budget from the application’s settings menu)
2. Navigate to the actual-server directory:

   cd ~/applications/actual-budget/actual-server

3. Stop the Actual Budget service:

   sudo systemctl stop actual.service

4. Pull the latest changes from GitHub:

   git pull

5. Update dependencies:

   yarn install

6. Restart the service:

   sudo systemctl start actual.service

Check the release notes or changelog to understand what’s new or changed in the latest update. Major updates might require additional migration steps not covered in this basic update procedure.

Troubleshooting Common Issues

Even with careful installation, you might encounter issues with Actual Budget. Here are solutions to some common problems:

The application doesn’t start:

• Check service status: sudo systemctl status actual.service
• Examine logs: journalctl -u actual.service
• Verify Node.js version: node --version
• Ensure all dependencies are installed: cd ~/applications/actual-budget/actual-server && yarn install

Cannot connect to the application:

• Verify the service is running: sudo systemctl status actual.service
• Check the configuration in config.json for correct hostname and port
• Test connectivity: curl http://localhost:5006
• Check for firewall issues: sudo ufw status

Database errors:

• Back up any existing data using the export feature
• Check permissions on the data directory
• Ensure sufficient disk space: df -h

Browser compatibility issues:

• Try a different browser (Chrome, Firefox, Safari)
• Clear browser cache and cookies
• Disable browser extensions that might interfere

Basic Usage Guide

Once installed, Actual Budget offers a wealth of features for managing your finances effectively. Here’s a brief overview to get you started:

Creating your first budget:

• Set up income categories to track different revenue sources
• Establish spending categories aligned with your financial goals
• Allocate available funds to each category following the envelope principle

Importing transactions:

• Connect bank accounts through SimpleFIN or GoCardless integration
• Import transaction data from CSV, QFX, OFX, or QIF files
• Review and categorize imported transactions for accurate reporting

Reports and visualizations:

• Track spending patterns through customizable reports
• Monitor net worth across all accounts
• Analyze monthly trends to identify areas for improvement

Multi-device synchronization:

• Set up additional devices following the same connection procedure
• Enable end-to-end encryption for sensitive financial data
• Establish regular backup procedures for data protection

Congratulations! You have successfully installed Actual Budget. Thanks for using this tutorial for installing Actual Budget on Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the official Actual Budget website.