Skip to content

Getting Started

This guide will get you up and running with FastSvelte in under 10 minutes. By the end, you'll have a fully functional SaaS application running locally with authentication, user management, and payment processing.

Prerequisites

Before you begin, make sure you have the following installed:

  • Docker - For running PostgreSQL and containerized setup
  • Python 3.12+ - For the FastAPI backend
  • Node.js 22+ - For the SvelteKit frontend
  • Sqitch - For database migrations (installation guide)
  • Stripe CLI - For testing webhooks locally (installation guide)
  • pgAdmin or similar PostgreSQL client for database management
  • REST Client VS Code extension (Recommended), Insomnia, or Postman for testing endpoints

Quick Setup (3 Steps)

1. Clone the Repository

# Clone the repository (choose SSH or HTTPS)

# Option 1: SSH (recommended if you have SSH keys configured)
git clone git@github.com:harunzafer/fastsvelte.git my-project

# Option 2: HTTPS (requires Personal Access Token)
git clone https://github.com/harunzafer/fastsvelte.git my-project

cd my-project

# Remove the original remote (prevents accidental pushes to FastSvelte repo)
git remote remove origin

Note: GitHub no longer supports password authentication. If you don't have SSH keys set up, you'll need to use a Personal Access Token instead of your password.

2. Run Interactive Setup

# Run the interactive setup script
python3 init.py

# Or preview changes without executing (dry-run mode)
python3 init.py --dry-run

The script will:

  • Check that all prerequisites are installed
  • Ask you for configuration (app name, mode, database settings, etc.)
  • Generate all .env files with your configuration
  • Update database schema names
  • Set up Docker PostgreSQL database
  • Run database migrations (includes seed data)
  • Set up backend (Python virtual environment + dependencies)
  • Set up frontend (npm install + API client generation)
  • Set up landing page (npm install)

This takes about 3-5 minutes depending on your internet speed.

Tip: Use --dry-run to preview what the script will do without making any changes.

Cleanup After Setup

Once your setup is complete and working, you can safely delete init.py - it's only needed for initial setup. The same applies to the /docs folder: either update it for your own project documentation or delete it entirely.

Review and Commit Changes

After init.py completes successfully, review what was changed:

# See all modified files
git status

# Review all changes
git diff

# IMPORTANT: Update CLAUDE.md with your project description
# Edit the Project Overview section to describe your application
# Replace the TODO placeholder with your app's purpose and features

# Commit the customizations
git add .
git commit -m "Initial project setup and customization"

3. Create Your First Admin User

Once the init script completes successfully, create a system administrator account:

cd backend
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python scripts/create_admin.py

The script will prompt you for:

  • Email address - Defaults to admin+dev@{yourapp}.com for localhost databases
  • Password - Minimum 8 characters
  • First name - Defaults to "System"
  • Last name - Defaults to "Admin"

What happens:

  • Creates a sys_admin user in the "System Administration" organization
  • The sys_admin role has application-wide permissions (not limited to one organization)
  • No email verification required

Tip: We recommend different email aliases for each environment:

  • Development (localhost): admin+dev@yourapp.com
  • Beta/Staging: admin+beta@yourapp.com
  • Production: admin@yourapp.com

All emails go to the same inbox, but you can easily identify which environment they're from.

Troubleshooting:

  • If you see "Organization 'System Administration' not found", run database migrations first
  • If the user already exists, the script will notify you

Email Verification in Development

In development mode, the email service defaults to stub (no actual emails sent). When registering new users, look for [STUB EMAIL] blocks in the backend logs - they contain the verification link you can copy/paste to complete registration.

4. Start Your Application

After creating your admin user, start the services:

# Terminal 1: Start the backend
cd backend
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Terminal 2: Start the frontend
cd frontend
npm run dev

# Terminal 3 (optional): Start the landing page
cd landing
npm run dev

5. Access Your Application

Login with the admin credentials you just created.

6. Explore the Application

After logging in, you can:

  • User management - View and manage users
  • Organization settings - Configure your organization
  • System analytics - View usage statistics
  • AI Note Improver - Test the demo application with note creation and AI-powered improvements

Explore the API

Visit http://localhost:8000/docs for interactive API documentation.

Environment Variables

The backend environment variables are in backend/.env using the FS_ prefix. These are loaded using Pydantic Settings. Here are the core variables you should be aware of:

  • FS_APP_NAME: Your application name
  • FS_MODE: b2c or b2b (see B2B Mode for details)
  • FS_ENVIRONMENT: dev, beta, or prod
  • FS_DB_URL / FS_DB_SCHEMA: Database connection
  • FS_BASE_WEB_URL / FS_BASE_API_URL: Frontend and backend URLs
  • FS_JWT_SECRET_KEY: OAuth state validation (auto-generated)
  • FS_CRON_SECRET: Cron job authentication (auto-generated)

Additional .env files exist in frontend/, landing/, and db/ directories for their respective configurations.

Automatic Configuration

The init.py script automatically generates all .env files with core variables. You typically only need to manually configure environment variables when adding integrations (email, payments, OAuth).

See the .env.example files in each directory for a full list of available environment variables.

See the Integrations Guide for instructions on configuring email services, payment gateways, and OAuth providers.

Next Steps

Now that you have FastSvelte running: