Quick Start

Get ReadyKit up and running in 5 minutes.

Prerequisites

• Python 3.11+
• Git
• uv (fast Python package manager)

Local Setup

1. Install uv

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

# Or with pip
pip install uv

2. Clone and Setup

git clone git@github.com:level09/readykit.git
cd readykit
./setup.sh

The setup script will:

• Create a Python virtual environment
• Install core and development dependencies via uv
• Generate a .env file with secure random keys
• Use SQLite for data and sessions, with no Redis service required

For Redis sessions and Celery, run ./setup.sh --full and start Redis locally. Selecting Docker during setup also installs and configures the full stack.

3. Initialize the Application

Configure OAuth in .env, or set GOOGLE_AUTH_ENABLED=False to use only the admin email/password login. Check the configuration before starting:

uv run python checks.py --config

This command checks required secrets, the database URL format, enabled OAuth settings, and optional dependencies without starting the app or contacting services. It names missing settings without displaying secret values and returns exit code 1 on failure. Use --config --billing to also check the selected provider's required billing settings. Passing does not verify credentials, connections, schema, or workers.

uv run flask create-db    # Create database tables
uv run flask install      # Create admin user (interactive)
uv run flask run          # Start development server

After initializing the database, uv run python checks.py runs the existing app and database smoke checks.

Visit http://localhost:5000 - you're ready to go!

TIP

The first user created with flask install becomes a superadmin with full platform access.

Add Redis and Celery Later

Keep your existing .env and keys. Install the optional dependencies:

uv sync --extra dev --extra full

Start Redis, then uncomment REDIS_SESSION, CELERY_BROKER_URL, and CELERY_RESULT_BACKEND in .env. Restart the app and start a Celery worker.

What Happens on First Login?

New OAuth accounts receive a workspace. A non-superadmin with one workspace goes straight to it; users with several workspaces select one. Team and settings pages remain visible according to role, even for a one-person workspace.

The superadmin created by flask install starts at the dashboard and can create workspaces there. Email/password self-registration and email invitations are not enabled.

Docker Setup (Production)

Generate the Docker configuration, then start the stack:

./setup.sh  # Select Docker and review the generated .env
docker compose up --build

This starts:

• Flask app via uWSGI
• PostgreSQL database
• Redis for sessions and Celery
• Nginx reverse proxy
• Celery worker for background tasks

Environment Configuration

Key variables in .env (auto-generated by setup.sh):

# Security (auto-generated)
SECRET_KEY=your_secure_key
SECURITY_PASSWORD_SALT=your_salt
SECURITY_TOTP_SECRETS=your_totp_secrets

# Database
SQLALCHEMY_DATABASE_URI=sqlite:///enferno.sqlite3  # Dev
# SQLALCHEMY_DATABASE_URI=postgresql://user:pass@localhost/db  # Production

# Optional Redis and Celery (enabled by --full)
# REDIS_SESSION=redis://localhost:6379/1
# CELERY_BROKER_URL=redis://localhost:6379/2
# CELERY_RESULT_BACKEND=redis://localhost:6379/3

# OAuth (optional but recommended)
GOOGLE_AUTH_ENABLED=true
GOOGLE_OAUTH_CLIENT_ID=your_client_id
GOOGLE_OAUTH_CLIENT_SECRET=your_secret

GITHUB_AUTH_ENABLED=true
GITHUB_OAUTH_CLIENT_ID=your_client_id
GITHUB_OAUTH_CLIENT_SECRET=your_secret

# Billing (Stripe or Chargebee)
BILLING_PROVIDER=stripe  # or chargebee
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PRO_PRICE_ID=price_...
STRIPE_WEBHOOK_SECRET=whsec_...

Common Commands

# Development
uv run flask run              # Start dev server
uv run flask create-db        # Initialize a fresh database and stamp migrations
uv run flask db upgrade       # Apply migrations to an existing database
uv run flask install          # Create admin user

# User management
uv run flask create -e user@example.com   # Prompts for a password
uv run flask reset -e user@example.com    # Prompts for a new password

# Code quality
uv run ruff check --fix .     # Lint and auto-fix
uv run ruff format .          # Format code

# Background tasks (requires the full setup and Redis)
uv run celery -A enferno.tasks worker --loglevel=info

Next Steps

Guide	Description
Workspaces	Understand multi-tenant architecture
Billing	Set up Stripe or Chargebee
Teams	Configure team management
Authentication	Configure OAuth and 2FA