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 18+ - For the SvelteKit frontend
  • Git - For cloning the repository
  • 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

2. 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.in
pip install -r requirements.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). 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

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

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