Self-host FinX

Run the FinX server on your own hardware and connect the Android app and the web app to it. The self-hosted server is free and source-available under Apache 2.0 with the Commons Clause. The code is on GitHub.

Requirements

• Docker with Docker Compose, or Debian 12 or newer, or Ubuntu 22.04 or newer.
• Without Docker: Node.js 20.19 or newer and PostgreSQL. The Debian and Ubuntu installer sets up both.
• About 300 MB of disk space.
• An HTTPS address for the server, because the Android app connects only over HTTPS.

Install with Docker Compose

1. Get the code. Clone the repository and change into its folder.

   git clone https://github.com/IT-BAER/finx.git
   cd finx

2. Set the configuration. Edit the .env file. DB_NAME, DB_USER, DB_PASSWORD and JWT_SECRET are required. Use a long random value for JWT_SECRET. Set DISABLE_REGISTRATION=true so that nobody can sign up on their own; the admin then creates the accounts.
3. Start the services. Build and start the containers. The web app answers on port 3000, and the API is available under /api.

   docker compose up -d --build

4. Get the admin account. On the first start, the backend writes generated admin credentials to its log.

   docker compose logs backend

Install on Debian or Ubuntu without Docker

The installer sets up Node.js and PostgreSQL, creates the database and its user, writes the configuration to /etc/finx/finx.env, builds the web app, creates the systemd service finx.service and can configure Nginx or Apache.

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/IT-BAER/finx/main/setup.sh)"

The installer shows the admin credentials once, at the end of the first installation.

Put HTTPS in front of the server

The Docker setup serves plain HTTP on port 3000. Put a reverse proxy with a TLS certificate in front of it, for example Nginx.

• The server sends live updates as Server-Sent Events at /api/events. Turn off response buffering for this path in the proxy, or updates arrive late.
• Set CORS_ORIGIN to the address of your web app.

Connect the apps

1. Install the Android app. Install FinX from Google Play. Android 11 or newer is required.
2. Enter your server address. In the setup, choose your own server and enter its HTTPS address, for example https://finx.example.com. The app checks /api/health before it continues.
3. Sign in. Sign in with an account on your server. Open the same address in a browser to use the web app.

Update the server

Docker

git pull
docker compose pull
docker compose build --no-cache
docker compose up -d
docker compose exec backend npm run migrate-db

Debian or Ubuntu

Run the installer again. It updates the existing installation in place.

AI features and Bank Sync

• Server AI features (receipt scanning, notification and voice parsing, AI chat) need an OpenRouter API key in OPENROUTER_API_KEY.
• By default, only admin accounts can use them. Set AI_ALLOW_NON_ADMIN=true to allow all users.
• Bank Sync is not part of the self-hosted server. It is available only on managed hosting at myfinx.app.

The features page shows which Pro features the app unlocks with a self-hosted server.

Security checklist

• Use a long random JWT_SECRET.
• Serve the server only over HTTPS.
• Set DISABLE_REGISTRATION=true on a private server.
• Give the database user only the rights FinX needs.
• Set CORS_ORIGIN to your web app address.
• Back up the PostgreSQL database regularly, for example with pg_dump.

Read the licence before you offer the server to other people.