Skip to content

getting-started.md

Latest commit

 

History

History
188 lines (139 loc) · 5.58 KB

getting-started.md

File metadata and controls

188 lines (139 loc) · 5.58 KB
Raw

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

Google and GitHub login are optional: each appears once its client ID and secret are set in .env. Without them, sign in with the admin from flask install. 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 (macOS: --port 5050 if AirPlay holds 5000)

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.

Provision Postgres with Stripe Projects

Stripe Projects can create a hosted Postgres database and write its DATABASE_URL to .env. Provision first, then let setup keep it:

stripe projects init
stripe projects add neon/postgres
./setup.sh --yes            # Keeps the provisioned DATABASE_URL
uv run flask create-db
uv run flask stripe-setup   # After setting STRIPE_SECRET_KEY: Pro price, webhook secret
uv run python checks.py --config --billing

ReadyKit reads SQLALCHEMY_DATABASE_URI first and falls back to DATABASE_URL. --yes skips prompts, does not configure Docker, and regenerates an existing .env after backing it up, keeping its DATABASE_URL.

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; a provider is enabled when both values are set)
GOOGLE_OAUTH_CLIENT_ID=your_client_id
GOOGLE_OAUTH_CLIENT_SECRET=your_secret

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