Installation

Quick Start (Docker — Recommended)

The fastest way to get running. Requires only Docker.

git clone https://github.com/fullfinity/fullfinity.git
cd fullfinity
docker compose up

This starts:

• Fullfinity at http://localhost:8000 (compiled engine + built frontend)
• PostgreSQL 16 database
• Valkey 8 cache

On first run, config.yaml is created automatically with defaults that work out of the box.

Project Structure

After setup, your project directory looks like:

fullfinity/
├── docker-compose.yml        # Service definitions
├── config.yaml               # Your configuration (mounted; lists ADDON_PATHS)
├── config.example.yaml       # Reference config with all options
└── addons/                   # Your modules (volume-mounted; listed in ADDON_PATHS)
    └── my_module/
        ├── manifest.json
        ├── models/
        ├── views/
        └── security/

The Docker image contains the compiled engine, pre-built React frontend, and all standard modules. Your config.yaml and your mounted addon folders persist across upgrades. There is no built-in modules folder — each addon folder you mount is loaded only because it’s listed under ADDON_PATHS in config.yaml.

Upgrading

git pull                  # get updated modules, views, data files
docker compose pull       # get updated engine + frontend image
docker compose up

Your configuration and custom modules are untouched.

Installing Modules

After the server is running, create a database and install modules:

1. Open http://localhost:8000
2. Use the database selector to create a new database
3. Go to Settings > Modules to install modules (sales, invoicing, inventory, etc.)

Or via CLI:

docker compose exec fullfinity ./fullfinity-server -c /app/config.yaml -db mycompany --init core,sales,invoicing --stop-after-init

Native Install (Advanced)

For developers who prefer running without Docker. Requires Python 3.12, PostgreSQL 14+, and Valkey/Redis.

Caution

The native install requires an engine package. The engine is distributed as a compiled binary and is included in the Docker image. For native installs, you need access to the fullfinity-engine package.

1. Prerequisites

• Python 3.12
• PostgreSQL 14 or higher
• Valkey or Redis

2. Create a PostgreSQL Database

CREATE USER fullfinity WITH PASSWORD 'fullfinity';
CREATE DATABASE fullfinity OWNER fullfinity;

3. Clone and Install

git clone https://github.com/fullfinity/fullfinity.git
cd fullfinity
python -m venv venv
source venv/bin/activate    # On Windows: venv\Scripts\activate
pip install -r requirements.txt

4. Configure

cp config.example.yaml config.yaml

Edit config.yaml — for native installs, set the database and cache hosts to localhost:

DB_HOST: "localhost"
VALKEY_HOST: "localhost"

See Configuration for all available options.

5. Start the Server

./fullfinity-server -c config.yaml

The application is available at http://localhost:8000.

Verify Installation

1. Open http://localhost:8000 — you should see the login page or database selector
2. Create a database and install the core module
3. Log in with the admin credentials you set during database creation

Next Steps

• Configuration — All config options explained
• CLI Reference — Server and module management commands
• Quick Start — Create your first module