Developing Modules

This guide sets up a local environment for building Fullfinity modules. The engine runs (closed) in a container; you edit your modules on your machine in your normal editor, with full autocomplete.

Get the workspace

Start from the deploy/ folder — the same Compose stack you run in development and production. It has everything preconfigured: a docker-compose.yml, a config.example.yaml, an addons/ folder for your modules (mounted into the container and listed under ADDON_PATHS), type stubs for editor autocomplete (typings/), and an AGENTS.md for AI assistants.

Open the folder in VS Code (or your editor of choice), then create your config from the example:

cp config.example.yaml config.yaml

Your config.yaml and addons/ are git-ignored, so pulling a new Fullfinity release never conflicts with your edits.

Autocomplete works immediately

Type stubs for the Fullfinity API ship in the workspace under typings/, so as soon as you open the folder you get autocomplete and type-checking for from fullfinity.engine.base import * — including your own model fields (a Char field reads back as str, an Integer as int, and so on). Nothing to install. The engine itself never leaves the container.

Start the runtime

docker compose up

This starts the Fullfinity engine, PostgreSQL, and Valkey. Open http://localhost:8000 and create a database when prompted. The engine runs with --reload, so it picks up your Python edits automatically.

Add a module

Put a module folder under addons/. Either scaffold a fresh one:

docker compose exec -w /app/addons fullfinity fullfinity new my_module

…which writes the full standard structure (manifest, a sample model, list/form views, a menu, a security group, and a test) into addons/, or bring an existing module by copying its folder into addons/.

The addons/ folder is loaded because config.yaml lists /app/addons under ADDON_PATHS — there is no magic folder. To load modules from other locations on disk, mount each at its own /app/addons/<name> in docker-compose.yml and add a matching line to ADDON_PATHS.

Install, run, test

# Create the database (if you haven't) and install your module:
docker compose exec fullfinity fullfinity -db dev --init my_module

# Run its tests:
docker compose exec fullfinity fullfinity -db dev test --module my_module

fullfinity here is an alias for fullfinity-server inside the image.

The edit loop

Edit your module under addons/ in your editor. Because the server runs with --reload, your Python changes are picked up without a manual restart. (View YAML changes apply on a module upgrade.)

Viewing logs

The engine logs every request and your module’s own logger/print output to stdout, so:

docker compose up                  # foreground: logs stream live
docker compose logs -f fullfinity  # if you started with `up -d`

Next steps

• Quick Start — build a complete example module step by step.
• Full reference: models, fields, views, security, and the CLI elsewhere in these docs.