Skip to content

1. SETUP.md

Latest commit

 

History

History
99 lines (67 loc) · 4.06 KB

1. SETUP.md

File metadata and controls

99 lines (67 loc) · 4.06 KB
Raw

Setup Guide

This guide gets the FireForm backend running locally with Docker. It assumes you are comfortable with git and a terminal, but new to this project.

Prerequisites

  • Docker 24 or newer, with the Docker daemon running
  • Docker Compose v2 (bundled with Docker Desktop; verify with docker compose version)
  • make
  • ~3 GB of free disk space (Docker images + LLM model weights)

Setup

1. Clone the repository

git clone https://github.com/fireform-core/FireForm.git
cd FireForm

2. Run first-time setup

make init

This will:

  1. Check that Docker meets the requirements above
  2. Create docker/.env.dev from docker/.env.example (gitignored; defaults work out of the box)
  3. Prompt you to pick an Ollama model (the default, qwen2.5:1.5b, is the smallest and fine for development)
  4. Offer to build and start everything answer y, or run make fireform later

3. Build and start (if you skipped it in step 2)

make fireform

This builds the Docker images, starts the containers, waits for Ollama, and pulls the LLM model. The first run takes several minutes (image build + model download); later runs are fast.

When it finishes you'll see:

FireForm is ready!
   API:      http://localhost:8000
   API Docs: http://localhost:8000/docs

4. Verify it works

Open http://localhost:8000/docs in your browser. This is the interactive Swagger UI you can explore and test every API endpoint directly from there (expand an endpoint, click Try it out, then Execute).

Day-to-day commands

Command What it does
make up Start containers
make down Stop containers (data is preserved)
make logs Stream all container logs (make logs-app / make logs-ollama for one)
make shell Open a shell inside the app container
make test Run the test suite
make help List all commands

The dev container mounts the source code, so code changes reload automatically — no rebuild needed. Rebuild (make build) only when dependencies in requirements.txt or the Dockerfile change.

Frontend (optional)

The desktop/web frontend lives in a separate repository:

git clone https://github.com/fireform-core/fireform-frontend.git

Follow the README in that repository to run it. The backend from this guide must be running for the frontend to work.

Troubleshooting

make init fails dependency checks Docker isn't running or is too old. Start Docker Desktop (or the Docker daemon) and confirm docker version reports 24+.

Port 8000 already in use Another process is bound to the port. Either stop it, or change APP_PORT in docker/.env.dev and run make down && make up.

Model pull is slow or times out The first make fireform downloads the LLM weights (~1 GB for the default model). On a slow connection just wait, or re-run make pull-model it resumes safely.

Containers start but the API doesn't respond Check make logs-app for the actual error. The entrypoint runs database migrations on startup, so the API takes a few seconds after the container starts.

Want a clean slate make super-clean stops everything and deletes all volumes database, uploads, and downloaded model weights. Only use it when you intend to wipe all local data.

Where to go next