Gravity Gravity Docs

Getting Started

Two steps: install the prerequisites, then install Gravity itself. Both are idempotent one-shot scripts — safe to run even if some of this is already on your machine, and safe to run again any time.

1. Prerequisites

Six things, installed once: Homebrew (macOS only), Git, the GitHub CLI (gh), Node.js, a text editor (VS Code), and an AI coding agent (Claude Code and/or Codex CLI). One script per OS installs all of them, checking what you already have before installing anything:

# macOS
curl -fsSL https://gitlab.com/eim_opensource/gravity-python/-/raw/master/scripts/install_tools_macos.sh | bash

# Linux (detects apt / dnf / pacman automatically)
curl -fsSL https://gitlab.com/eim_opensource/gravity-python/-/raw/master/scripts/install_tools_linux.sh | bash

# Windows (PowerShell, uses winget)
iwr https://gitlab.com/eim_opensource/gravity-python/-/raw/master/scripts/install_tools_windows.ps1 -UseBasicParsing | iex

An AI agent with shell access can run any of these directly — see views/gravity/install-your-tools.j2 (the /install-your-tools page) for ready-to-paste prompts per OS if you're driving this from Claude Code, Claude Desktop, or Codex.

Already have these? Skip this step entirely — scripts/install.sh below only needs git and Python 3.10+.

2. Install and run Gravity

One command clones the repo, installs dependencies, and starts a local server — natively with Gunicorn by default (no Docker required):

curl -fsSL https://gitlab.com/eim_opensource/gravity-python/-/raw/master/scripts/install.sh | bash

This clones into ~/projects/opensource/gravity (override with GRAVITY_INSTALL_DIR), creates a virtualenv, installs requirements.txt, and starts the server detached in the background — the script always returns, which is what lets an AI agent drive it without anything to sit and wait on.

Run it again any time to control that install instead of reinstalling:

install.sh                 Status if running, otherwise start it
install.sh --docker        (Re)start via Docker instead of natively
install.sh --theme=photo   Switch the active theme and restart
install.sh --update        git pull, reinstall deps, restart
install.sh --restart       Stop then start again
install.sh --stop          Stop the running server
install.sh --status        Print whether it's running and its URL
install.sh --logs          Tail the server log (Ctrl+C to stop watching)
install.sh --foreground    Run attached instead of backgrounded (native only)
install.sh --dir=PATH      Install elsewhere (default: ~/projects/opensource/gravity)
install.sh --port=PORT     Host port (default: 8000)

Flags compose: install.sh --theme=clarity --docker switches theme and mode together. The script never prompts and always exits — piping it, or driving it from an AI agent, works exactly like a human terminal.

Already have the repo cloned?

cp .env.example .env
make dev            # docker compose up (Gunicorn mode, matches a standalone-server deploy)
# or
make run-local       # uvicorn asgi:app --reload — fastest local iteration, hot reload

make dev/make up (Docker Compose) and make run-local (bare Uvicorn with --reload) are two intentionally different paths — see Deployment for why the process-management story differs between "developing against a persistent local instance" and "fast iteration with hot reload."

What you get

A running Gravity site at http://localhost:8000 (or your --port), with:

  • The public site — home, blog, events, and (depending on theme) a link-in-bio page, scheduling pages, and a customer portal — all working immediately against local JSON storage, no database or signup required.
  • /admin — locked by default. Set GRAVITY_DEV_ADMIN=1 (make editor does this for you, plus seeds sample content) to test the Visual Editor and admin dashboard without a real Adhara account. Never set this on a real deployment.
  • Five themes to try: GRAVITY_TEMPLATE=gravity|clarity|photo|resonance|stripe (or install.sh --theme=x).

Next steps

  • Architecture — how a request actually flows once it's running, and where to make your first change.
  • Backend & Adhara — local JSON gets you a working demo; read this before you need real persistence, a CMS, or email.
  • Deployment — take it from your machine to Vercel, Cloud Run, Cloudflare, or Azure with one command: make deploy. make push-repo creates a GitHub/GitLab repo and pushes your code first, if you want Vercel to rebuild automatically on every future push (VERCEL_LINK_GIT=1).
Edit this page on GitLab ↗