Installation

Step-by-step guide to installing Singularity, configuring your environment, and running the development and production servers.

Prerequisites

Before you begin, make sure you have the following installed on your system:

Requirement	Version	Purpose
Python	3.12+	Runtime for the application and all CLI tools
uv	Latest	Fast Python package manager (replaces pip/poetry)
Redis	6.0+	Message broker for Celery tasks, RPC heartbeat, and Pub/Sub
PostgreSQL	14+	Primary database (optional for simple demos -- a dummy URL is provided by default)

Installing uv

If you do not have uv installed yet, you can install it with a single command:

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

pip install uv

Install Singularity

pip install singularity-fm

Or with extras:

pip install singularity-fm[sql,tasks]   # SQL + background tasks
pip install singularity-fm[mongo]       # MongoDB (Async PyMongo + Beanie)
pip install singularity-fm[all]         # Everything

Scaffold the project

Singularity must already be installed (step 1), so the project directory and Python environment already exist. singularity new lays the framework files into the current directory — it does not create a new folder:
```
mkdir my-project && cd my-project
uv init                       # or any tool that creates a Python env
uv add singularity-fm[sql,tasks]
uv run singularity new        # name defaults to the directory's name
```
This adds app.py, settings.py, .env, and empty directories for services, tasks, and models. Existing files are never overwritten (pass --force to replace them). Pass singularity new <name> to override the project name used in generated files.

Configure your environment

Edit .env to match your local infrastructure:

ENVIRONMENT=dev
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/my_project
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0
JWT_SECRET=your-secret-key
RPC_BASE_URL=http://localhost:8000

See the Configuration page for a complete list of all environment variables.

Generate your first service
```
singularity generate service users
```
Start the dev server
```
singularity dev
```
Open http://localhost:8000/docs to see your service in the Swagger UI.

Running the Server

Development Mode

Development mode uses Uvicorn with hot reload:

singularity dev

Options:

singularity dev --port 3000             # Custom port
singularity dev --no-heartbeat          # Disable RPC heartbeat (no Redis needed)

Production Mode

Use Gunicorn with Uvicorn workers:

gunicorn app:app.fastapi \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --workers 4

Verifying the Installation

Once the server is running, verify it is responding correctly:

# Open the interactive API docs in your browser
curl http://localhost:8000/docs

# Check the RPC spec endpoint (returns the registry of all RPC-exposed services)
curl http://localhost:8000/_rpc/spec

You can also open http://localhost:8000/docs in your browser to see the Swagger UI with all auto-discovered service routes.

CLI Commands

After installing singularity-fm, the singularity CLI is available:

Command	Purpose
`singularity new [name]`	Scaffold framework files into the current directory
`singularity dev`	Start dev server with hot reload
`singularity generate service <name>`	Generate service boilerplate
`singularity generate task <name>`	Generate task boilerplate

singularity --help
singularity generate service payments --rpc --db

Next Steps

Project Structure -- Understand how the codebase is organized
Configuration -- Deep dive into settings and environment variables

Installation

On this page