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)
  • pgAdmin or similar PostgreSQL client for database management
  • Insomnia, Postman, or similar API client 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 5-10 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

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

  • Frontend Dashboard: http://localhost:5173
  • Backend API: http://localhost:8000
  • API Documentation: http://localhost:8000/docs
  • Landing Page: http://localhost:5174

Login with the admin credentials you just created.

What's Next?

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

FastSvelte uses environment variables with the FS_ prefix. These are loaded from backend/.env using Pydantic Settings.

Note: The init.py script automatically generates the .env file with all required variables. The configuration below is for reference when adding integrations or adjusting settings.

Core Variables

# Application
FS_APP_NAME="Your App Name"
FS_APP_DESCRIPTION="Your app description"
FS_MODE="b2c"  # or "b2b"
FS_ENVIRONMENT="dev"  # or "beta" or "prod"

# Database
FS_DB_URL="postgresql://postgres:postgres@localhost:5432/fastsvelte?sslmode=disable"
FS_DB_SCHEMA="fastsvelte"

# URLs
FS_BASE_WEB_URL="http://localhost:5173"
FS_BASE_API_URL="http://localhost:8000"

# Security (auto-generated by init.py)
FS_JWT_SECRET_KEY="your-generated-secret-key"
FS_CRON_SECRET="your-generated-cron-secret"

# OAuth - Google (required)
FS_GOOGLE_CLIENT_ID="your-google-client-id.apps.googleusercontent.com"
FS_GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Payments - Stripe (required)
FS_STRIPE_API_KEY="sk_test_your-stripe-secret-key"
FS_STRIPE_WEBHOOK_SECRET="whsec_your-webhook-secret"

Integrations (Add as needed)

# Email Service (default: stub for development)
FS_EMAIL_PROVIDER="sendgrid"  # or "azure" or "stub"

# SendGrid (if using SendGrid)
FS_SENDGRID_API_KEY="SG.your-sendgrid-api-key"
FS_SENDGRID_SENDER_ADDRESS="noreply@yourdomain.com"
FS_SENDGRID_SENDER_NAME="Your App Name"

# Azure Email (if using Azure)
FS_AZURE_EMAIL_CONNECTION_STRING="endpoint=https://your-resource.communication.azure.com/;accesskey=your-key"
FS_AZURE_EMAIL_SENDER_ADDRESS="noreply@yourdomain.com"

# AI - OpenAI (optional, for AI features like Note Improver)
FS_OPENAI_API_KEY="sk-proj-your-openai-api-key"

For complete configuration reference, see Integrations.

Keeping Dependencies Up-to-Date

Regular dependency upgrades keep your application secure and up-to-date. FastSvelte provides a structured upgrade process with automated tests to verify compatibility.

Backend Dependencies (Python)

FastSvelte uses pip-tools to manage Python dependencies with separate files for production and development:

  • backend/requirements.in - Production dependencies only
  • backend/requirements.dev.in - Development dependencies (testing, linting, etc.)

Upgrade workflow:

cd backend
source .venv/bin/activate

# 1. Upgrade dependencies
pip-compile --upgrade --no-strip-extras requirements.in
pip-compile --upgrade --no-strip-extras requirements.dev.in

# Or upgrade a specific package
pip-compile --upgrade-package fastapi --no-strip-extras requirements.in

# 2. Install the upgraded dependencies
pip install -r requirements.dev.txt

# 3. Run tests to verify compatibility
pytest

Note: Smoke tests in backend/test/smoke/ verify app startup, database connectivity, and API functionality. Database tests require PostgreSQL running (docker compose up db -d) but will skip gracefully if unavailable.

Frontend Dependencies (npm)

The frontend and landing page use package.json and package-lock.json for dependency management.

Upgrade workflow:

# Frontend
cd frontend

# 1. Check what's outdated
npm outdated

# 2. Update dependencies (respects semver ranges)
npm update

# 3. Run checks to verify compatibility
npm run build
npm run check
npm run lint
npm run test

# Landing page (simpler, no tests by default)
cd ../landing
npm outdated
npm update
npm run build
npm run check
npm run lint

For major version upgrades:

# Install npm-check-updates (one-time)
npm install -g npm-check-updates

# Frontend or landing - check what would be updated
cd frontend  # or cd landing
ncu

# Update package.json to latest versions
ncu -u

# Install and test
npm install
npm run build && npm run check && npm run lint
npm run test  # Frontend only (landing has no tests by default)

Important: - Commit package-lock.json after upgrades - Test thoroughly after major version updates - Update one component at a time (backend, frontend, landing) for easier troubleshooting - Frontend smoke tests: Located in frontend/src/tests/smoke/, automatically run with npm run test - Adding tests to landing: Run npx sv add vitest if you want to add testing capabilities

Next Steps

Now that you have FastSvelte running: