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 (recommended) - For running PostgreSQL and containerized setup
  • Python 3.12+ - For the FastAPI backend
  • Node.js 22+ - For the SvelteKit frontend
  • pgAdmin or similar PostgreSQL client for database management
  • Insomnia, Postman, or similar API client for testing endpoints

Quick Setup (5 Minutes)

1. Clone and Setup

# Clone the repository
git clone <your-fastsvelte-repo-url>
cd fastsvelte

# Create the external Docker volume (only needed once)
docker volume create fastsvelte-data

# Start PostgreSQL database
docker compose up db -d

# Run database migrations
cd ../db
cp .env.example .env
./sqitch.sh dev deploy

2. Create a migration to add seed data (optional)

# Create a new migration file
sqitch add add_seed_data -n "Add seed data"
cp b2c-seed.sql deploy/add_seed_data.sql
./sqitch.sh dev deploy

Copy this script to db/revert/add_seed_data.sql to revert the seed data if needed.

BEGIN;

DELETE FROM fastsvelte."user";
DELETE FROM fastsvelte.organization;
DELETE FROM fastsvelte.user_setting_definition;
DELETE FROM fastsvelte.organization_setting_definition;
DELETE FROM fastsvelte.system_setting_definition;
DELETE FROM fastsvelte.plan;
DELETE FROM fastsvelte.role;

COMMIT;

3. Backend Setup

cd backend

# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install pip-tools
pip-compile --no-strip-extras requirements.dev.in
pip install -r requirements.dev.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Run database migrations (this also creates the default admin user)
cd ../db
./sqitch.sh dev deploy

# Start the API server
cd ../backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

3. Frontend Setup

# In a new terminal
cd frontend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your API URL if different

# Generate API client from backend OpenAPI spec
npm run generate

# Start the development server
npm run dev

4. Access Your Application

  • Frontend Dashboard: http://localhost:5173
  • Backend API: http://localhost:8000
  • API Documentation: http://localhost:8000/docs
  • Landing Page: http://localhost:5174 (after setting up landing)

Environment Configuration

FastSvelte uses environment variables prefixed with FS_ (FastSvelte). These are being loaded from config/settings.py using Pydantic's BaseSettings. If there is a default value for a setting, defining a variable is optional. Copy the .env.example files and configure these essential variables:

Required Variables

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

# JWT for session management (generate with: openssl rand -base64 32)
FS_JWT_SECRET_KEY="your-secret-key-here"

# App configuration
FS_BASE_WEB_URL="http://localhost:5173"
FS_BASE_API_URL="http://localhost:8000"

# Email Service (choose one: stub, sendgrid, azure)
FS_EMAIL_PROVIDER="sendgrid"

# SendGrid email configuration
FS_SENDGRID_API_KEY="SG.your-sendgrid-api-key"
FS_SENDGRID_SENDER_ADDRESS="noreply@yourdomain.com"
FS_SENDGRID_SENDER_NAME="Your App Name"

# OR Azure email configuration
FS_EMAIL_PROVIDER="azure"
FS_AZURE_EMAIL_CONNECTION_STRING="endpoint=https://your-resource.communication.azure.com/;accesskey=your-key"
FS_AZURE_EMAIL_SENDER_ADDRESS="noreply@yourdomain.com"

# OAuth (Google)
FS_GOOGLE_CLIENT_ID="your-google-client-id"
FS_GOOGLE_CLIENT_SECRET="your-google-client-secret"

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

# Cron jobs protection
FS_CRON_SECRET="your-cron-secret"

First Steps After Setup

1. Login with Default Admin Account

When you run the database migrations, a default admin user is automatically created:

  • Email: admin@example.com
  • Password: test1234

2. Complete Initial Setup

  1. Visit the frontend: http://localhost:5173
  2. Log in with the default credentials above
  3. Complete the setup process: On first login, you'll be forced to:
  4. Change your email from @example.com to your real email
  5. Set a new secure password
  6. Update your first/last name if desired

3. Explore the Admin Dashboard

After completing setup, you can:

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

4. Test API Endpoints

Visit http://localhost:8000/docs to explore the interactive API documentation. You can also use Insomnia, Postman, or similar API clients to test key endpoints:

  • POST /api/auth/login - User authentication
  • GET /api/user/me - Get current user info
  • GET /api/user/list - List users (admin only)
  • GET /api/analytics/stats - Get system statistics

Development Workflow

Making Changes

  1. Backend changes: The API server will auto-reload with --reload flag
  2. Frontend changes: Vite provides hot module replacement
  3. Database changes: Use Sqitch migrations (see Architecture Overview for details)

Regenerating API Client

When you modify backend API routes or models:

cd frontend
npm run generate  # Regenerates the API client from OpenAPI spec

Running Tests

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm run test

Alternative Setup Methods

Option 1: Docker Everything

For a completely containerized setup:

# Create external volume
docker volume create fastsvelte-data

# Run everything in Docker
docker compose --env-file .env.docker up --build

# Access at:
# - Frontend: http://localhost:5173
# - Backend: http://localhost:8000

Option 2: Local Database + Docker Services

If you prefer a local PostgreSQL installation:

# Install PostgreSQL locally
# Update FS_DB_URL in backend/.env to point to your local database

# Start backend
cd backend && uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Start frontend
cd frontend && npm run dev

Replacing the Demo Application

Once you're familiar with FastSvelte, you'll want to replace the AI Note Improver demo with your own core SaaS functionality:

What to Keep

  • Authentication system - User login, registration, session management
  • Multi-tenant architecture - Organization-based user management
  • Billing integration - Stripe payments, subscription management, usage tracking
  • Admin dashboard - User management, analytics, settings
  • Core infrastructure - Database migrations, API patterns, frontend structure

What to Replace

  • Note-related models (app/model/note_model.py)
  • Note services (app/service/note_service.py, app/service/note_organizer_service.py)
  • Note API routes (app/api/route/note_route.py)
  • Note database tables (remove from Sqitch migrations)
  • Note frontend pages (replace with your app's main functionality)
  • OpenAI integration (unless your app needs AI features)

Migration Strategy

  1. Plan your domain models - Define your core business entities
  2. Create new database migrations - Add tables for your domain
  3. Implement repositories and services - Follow the existing patterns
  4. Build API routes - Use the note routes as a template
  5. Update frontend - Replace note pages with your app's UI
  6. Clean up - Remove unused note-related code

This approach lets you leverage FastSvelte's robust foundation while building your unique SaaS application.

Next Steps

Now that you have FastSvelte running locally:

  1. Architecture Overview - Understand how FastSvelte is structured
  2. Integrations - Set up email, payments, and OAuth

Common Issues

Port Conflicts

  • PostgreSQL: If port 5432 is in use, change the port in docker-compose.yml
  • Frontend: If port 5173 is in use, Vite will automatically use the next available port

Database Connection Issues

  • Ensure PostgreSQL is running: docker ps
  • Check database URL in backend/.env matches your setup
  • Verify migrations ran successfully: cd db && ./sqitch.sh dev status

API Client Generation Fails

  • Ensure backend is running when you run npm run generate
  • Check that orval.config.cjs points to the correct backend URL

Permission Denied on Scripts

chmod +x db/sqitch.sh

Default Admin Setup Issues

  • If you can't access admin@example.com, check that migrations ran successfully
  • The default admin is only created if no other sys_admin users exist
  • You must update both email and password on first login - @example.com emails are not allowed after setup

Getting Help

  • Check logs: Backend logs appear in terminal, frontend logs in browser console
  • API Documentation: Visit http://localhost:8000/docs for interactive API docs
  • Database: Use pgAdmin or similar tool to inspect database state
  • Issues: Check the repository issues page for known problems and solutions