Quick Start Guide - SnackBase

Get up and running with SnackBase in 5 minutes. This guide will walk you through the essential steps to set up your instance, create your first collection, add data, set up permissions, and make API requests.

Prerequisites

Before you begin, ensure you have:

Python 3.12+ installed
Node.js 18+ installed (for the admin UI)
uv package manager installed
- macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
- Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Git installed (for cloning the repository)

Windows Users: If you don’t have Node.js installed, download it from nodejs.org. For Python, use the Microsoft Store or python.org.

Step 1: Install and Start SnackBase

1.1 Clone the Repository

git clone https://github.com/yourusername/snackbase.git
cd SnackBase

1.2 Install Backend Dependencies

SnackBase uses uv for fast, reliable package management:

uv sync

1.3 Install Frontend Dependencies

Navigate to the UI directory and install Node.js dependencies:

cd ui
npm install
cd ..

1.4 Configure Environment

Create a .env file from the example template:

cp .env.example .env

For local development, the default values work fine. However, for production, update at minimum:

SNACKBASE_SECRET_KEY - Generate a secure random string
SNACKBASE_DATABASE_URL - Switch to PostgreSQL
SNACKBASE_CORS_ORIGINS - Add your frontend URL

1.5 Initialize the Database

uv run python -m snackbase init-db

This command:

Creates the database file at ./sb_data/snackbase.db
Runs Alembic migrations to set up all tables
Creates the system account (ID: SY0000) for superadmin operations

1.6 Configure Email (Optional but Recommended)

SnackBase requires email configuration for user email verification. Choose one of these options: Option A: Use a Development SMTP Server (Recommended for Testing)

# Install MailHog for local email testing
# macOS
brew install mailhog

# Start MailHog
mailhog

Then update your .env:

# For MailHog (localhost:1025)
EMAIL_PROVIDER=smtp
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USER=
SMTP_PASSWORD=
SMTP_FROM=[email protected]

Option B: Use Resend (Recommended for Production) Sign up at resend.com and get an API key:

EMAIL_PROVIDER=resend
RESEND_API_KEY=re_xxxxxxxxxxxxx
EMAIL_FROM=[email protected]

Option C: Use AWS SES

EMAIL_PROVIDER=aws_ses
AWS_SES_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
EMAIL_FROM=[email protected]

1.7 Create a Superadmin User

uv run python -m snackbase create-superadmin

You’ll be prompted to enter:

Email address (e.g., [email protected])
Password (minimum 8 characters, recommended: mix of letters, numbers, symbols)
Password confirmation

The superadmin account will require email verification if email is configured. You can verify the email via the API or auto-verify superadmin emails in development mode.

1.8 Start the Backend Server

uv run python -m snackbase serve

You should see output indicating the server is running:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.

1.9 Start the Frontend (New Terminal)

Open a new terminal and start the React development server:

cd ui
npm run dev

You should see:

VITE v7.x.x ready in xxx ms
➜  Local:   http://localhost:5173/

1.10 Access the Admin UI

Open your browser and navigate to:

http://localhost:5173

Step 2: Log In to the Admin UI

2.1 Enter Your Credentials

On the login page, enter:

Account: system (or SY0000)
Email: The superadmin email you created
Password: The superadmin password you created

Click Sign In.

The superadmin account is always linked to the system account (ID: SY0000). Use “system” as the account field when logging in.

2.2 Verify Your Email (If Required)

If email verification is enabled, you’ll see a message asking you to verify your email. For Development with MailHog:

Open http://localhost:8025 in your browser
Find the verification email
Click the verification link

To Skip Verification in Development: Use the admin API to verify your email:

# Get your access token first, then:
curl -X POST http://localhost:8000/api/v1/admin/verify-email \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

2.3 Welcome to the Dashboard

After logging in (and verifying your email if required), you’ll see the main dashboard with:

Sidebar navigation on the left
Statistics cards (collections, records, users, etc.)
Recent activity or quick actions

Step 3: Create Your First Collection

A Collection is like a table in a traditional database. It defines the structure of your data with fields and types.

3.1 Navigate to Collections

Click Collections in the sidebar.

3.2 Create a New Collection

Click the + New Collection button. A modal or form will appear. Enter:

Name: posts (this will become the API endpoint: /api/v1/records/posts)
Description: Blog posts and articles (optional)

Click Create.

3.3 Add Fields to Your Collection

After creating the collection, you’ll see the collection detail page. Now let’s add fields. Click + Add Field and add the following fields:

Field Name	Type	Required	Options
`title`	Text	Yes	-
`content`	Text	No	Multi-line: Yes
`status`	Select	Yes	Options: `draft`, `published`, `archived`
`published_at`	Date	No	-
`views`	Number	No	Default: `0`

Step 4: Add Your First Records

Now that your collection is set up, let’s add some data.

4.1 Navigate to Records

Click Records in the sidebar, then select the posts collection.

4.2 Create a Record

Click + New Record. Fill in the form:

title: My First Blog Post
content: This is my first post using SnackBase!
status: published
published_at: Select today’s date
views: Leave as 0 (default)

Click Save.

4.3 View Your Record

After saving, you’ll see your record in the data table.

4.4 Add More Records

Create a few more records to have some test data:

“Getting Started with SnackBase” (status: published)
“Draft Post About API Design” (status: draft)
“Archived Announcement” (status: archived)

Step 5: Set Up Roles and Permissions

SnackBase uses Role-Based Access Control (RBAC) to manage who can do what with your data.

5.1 Navigate to Roles

Click Roles in the sidebar.

5.2 Understand Default Roles

By default, you’ll see:

admin - Full access to all collections and operations

The superadmin user you created has the admin role.

5.3 Create a New Role

Click + New Role. Enter:

Name: editor
Description: Can create and edit posts, but cannot delete

Click Create.

5.4 Configure Permissions

On the role detail page for editor:

Click + Add Permission
Configure:
- Collection: posts
- Create: Enabled
- Read: Enabled
- Update: Enabled
- Delete: Disabled

Click Save.

5.5 Create a Read-Only Role

Repeat the process to create a viewer role:

Name: viewer
Collection: posts
Read: Enabled only

Step 6: Create Additional Users

Now let’s create users with different roles to test permissions.

6.1 Navigate to Users

Click Users in the sidebar.

6.2 Create an Editor User

Click + New User. Enter:

Email: [email protected]
Password: EditorPass123!
Role: editor
Active: Yes

Click Create.

6.3 Create a Viewer User

Repeat to create a viewer user:

Email: [email protected]
Password: ViewerPass123!
Role: viewer

Step 7: Make Your First API Request

SnackBase automatically generates REST APIs for your collections. Let’s test it!

7.1 Get Your Access Token

Open your browser’s developer tools:

Press F12 or Cmd+Option+I (Mac)
Go to the Application or Storage tab
Find Local Storage → http://localhost:5173
Copy the value of access_token

7.2 Test the API with curl

Open a new terminal and try fetching all posts:

curl http://localhost:8000/api/v1/records/posts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Replace YOUR_ACCESS_TOKEN with the token you copied.

7.3 Create a Record via API

Create a new post using the API:

curl -X POST http://localhost:8000/api/v1/records/posts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Created via API",
    "content": "This post was created using the REST API",
    "status": "published",
    "views": 0
  }'

7.4 Explore the Interactive API Docs

SnackBase includes auto-generated API documentation powered by Swagger UI. Open in your browser:

http://localhost:8000/docs

Step 8: Test Permissions

Let’s verify that the permission system works correctly.

8.1 Log In as Editor

Open an incognito/private window and navigate to:

http://localhost:5173

Account: system
Email: [email protected]
Password: EditorPass123!

8.2 Verify Edit Capabilities

Navigate to Records → posts. You should see:

Edit buttons on existing records
No Delete buttons (editor role cannot delete)

8.3 Test Delete Restriction

Try to delete a record using the API with editor credentials:

curl -X DELETE http://localhost:8000/api/v1/records/posts/RECORD_ID \
  -H "Authorization: Bearer EDITOR_ACCESS_TOKEN"

You should receive a 403 Forbidden error.

Development Commands

Backend Commands

# Server management
uv run python -m snackbase serve          # Start server (0.0.0.0:8000)
uv run python -m snackbase serve --reload # Dev mode with auto-reload
uv run python -m snackbase info           # Show configuration

# Database
uv run python -m snackbase init-db        # Initialize database (dev only)
uv run python -m snackbase create-superadmin  # Create superadmin user

# Interactive shell
uv run python -m snackbase shell          # IPython REPL with pre-loaded context

# Code quality
uv run ruff check .                        # Lint
uv run ruff format .                       # Format
uv run mypy src/                           # Type check

# Testing
uv run pytest                              # Run all tests
uv run pytest tests/unit/                  # Unit tests only
uv run pytest tests/integration/           # Integration tests only
uv run pytest --cov=snackbase              # With coverage
uv run pytest -k "test_name"               # Run specific test

Frontend Commands

cd ui
npm run dev        # Start dev server (Vite)
npm run build      # Production build
npm run lint       # ESLint
npm run preview    # Preview production build

Troubleshooting

Database Errors

Problem: sqlite3.OperationalError: unable to open database file Solution: Ensure the sb_data directory exists and is writable:

mkdir -p sb_data
chmod 755 sb_data

Windows: Create the folder manually in File Explorer if needed.

Port Conflicts

Problem: Error: listen tcp 0.0.0.0:8000: bind: address already in use Solution: Another process is using port 8000. Find and stop it: macOS/Linux:

# Find the process
lsof -ti:8000 | xargs kill -9

Windows:

# Find the process
netstat -ano | findstr :8000
# Kill the process (replace PID with the actual process ID)
taskkill /PID PID /F

Alternatively, change the port in .env:

SNACKBASE_PORT=8001

Email Verification Problems

Problem: Users can’t log in due to unverified email Solution: Manually verify the user via API:

curl -X POST http://localhost:8000/api/v1/admin/verify-email \
  -H "Authorization: Bearer YOUR_SUPERADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Problem: Verification emails not being sent Solution: Check your email configuration:

Verify email settings in .env
If using MailHog, ensure it’s running (mailhog command)
Check server logs for email errors

API Endpoints Reference

SnackBase provides 20+ API routers:

Router	Endpoints	Description
`/api/v1/auth`	Login, register, refresh, me	Authentication
`/api/v1/auth/oauth`	OAuth flow (Google, GitHub, etc.)	OAuth authentication
`/api/v1/auth/saml`	SAML SSO flow	SAML authentication
`/api/v1/accounts`	CRUD operations	Account management
`/api/v1/collections`	CRUD operations	Collection management
`/api/v1/records/{collection}`	CRUD operations	Dynamic collection records
`/api/v1/users`	CRUD operations	User management
`/api/v1/roles`	CRUD, permissions	Role management
`/api/v1/permissions`	CRUD operations	Permission management
`/api/v1/macros`	CRUD, execute	SQL macro management
`/api/v1/groups`	CRUD operations	Group management
`/api/v1/invitations`	Create, accept	User invitations
`/api/v1/dashboard`	Statistics	Dashboard data
`/api/v1/audit-logs`	List, export, filter	Audit log retrieval
`/api/v1/migrations`	Status, history	Alembic migration status
`/api/v1/files`	Upload, download, delete	File management
`/api/v1/admin`	System configuration	Admin controls
`/api/v1/admin/email`	Email templates, settings	Email management

Common Gotchas & Tips

Gotcha 1: Account Context in API Requests

When making API requests, your user is always associated with an account. All data is isolated by account_id, even if you’re using a single account setup. Solution: Be aware that filtering by account happens automatically. You don’t need to specify account_id in your queries.

Gotcha 2: Collection Names Become URL Endpoints

The collection name you choose becomes part of the API URL:

Collection blog-posts → /api/v1/records/blog-posts
Collection posts → /api/v1/records/posts

Solution: Use simple, URL-friendly names with lowercase letters, numbers, and hyphens.

Gotcha 3: Built-in Hooks Auto-Set Timestamps

Every record automatically gets created_at and updated_at timestamps. You don’t need to add these as fields. Solution: Don’t create manual timestamp fields—they’re built-in!

Gotcha 4: Superadmin vs Admin

Aspect	Superadmin	Admin (role)
Account	`system` (SY0000)	Any account
Access	All accounts	Single account

Solution: Use superadmin only for system-level operations. Use admin roles for day-to-day account management.

Gotcha 5: Permission Caching

Permissions are cached for 5 minutes. If you change a role’s permissions, it may take up to 5 minutes to take effect. Solution: Wait 5 minutes or restart the server after permission changes for immediate effect.

Production Considerations

Before deploying to production, review these important security and configuration items:

Security Settings

# Generate a secure secret key
python -c "import secrets; print(secrets.token_urlsafe(32))"

# Update .env with secure values
SNACKBASE_SECRET_KEY=your_generated_secret_key_here

Database Setup

For production, switch from SQLite to PostgreSQL:

# Install PostgreSQL
# macOS
brew install postgresql

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib

# Update .env
SNACKBASE_DATABASE_URL=postgresql+asyncpg://user:password@localhost/snackbase

Environment Variables

Key production environment variables:

# Required
SNACKBASE_SECRET_KEY=<generate with secrets.token_urlsafe(32)>
SNACKBASE_DATABASE_URL=postgresql+asyncpg://...

# Recommended
SNACKBASE_ENVIRONMENT=production
SNACKBASE_DEBUG=false
SNACKBASE_CORS_ORIGINS=https://yourdomain.com

# Email Configuration
EMAIL_PROVIDER=smtp  # or resend, aws_ses
SMTP_HOST=smtp.yourprovider.com
SMTP_PORT=587
SMTP_USER=your_email
SMTP_PASSWORD=your_password
SMTP_FROM=[email protected]

Next Steps

Congratulations! You’ve completed the SnackBase Quick Start. Here’s what to explore next:

Deployment Guide - Deploy SnackBase in development and production
Authentication Model - Deep dive into auth, multi-account users, and tokens
Multi-Tenancy Model - How accounts and data isolation work
Hooks System - Automate workflows with event-driven hooks
API Examples - Practical API usage examples

Getting Started

Deployment

Developer Guides

OAuth Setup

SAML Setup

​Prerequisites

​Step 1: Install and Start SnackBase

​1.1 Clone the Repository

​1.2 Install Backend Dependencies

​1.3 Install Frontend Dependencies

​1.4 Configure Environment

​1.5 Initialize the Database

​1.6 Configure Email (Optional but Recommended)

​1.7 Create a Superadmin User

​1.8 Start the Backend Server

​1.9 Start the Frontend (New Terminal)

​1.10 Access the Admin UI

​Step 2: Log In to the Admin UI

​2.1 Enter Your Credentials

​2.2 Verify Your Email (If Required)

​2.3 Welcome to the Dashboard

​Step 3: Create Your First Collection

​3.1 Navigate to Collections

​3.2 Create a New Collection

​3.3 Add Fields to Your Collection

​Step 4: Add Your First Records

​4.1 Navigate to Records

​4.2 Create a Record

​4.3 View Your Record

​4.4 Add More Records

​Step 5: Set Up Roles and Permissions

​5.1 Navigate to Roles

​5.2 Understand Default Roles

​5.3 Create a New Role

​5.4 Configure Permissions

​5.5 Create a Read-Only Role

​Step 6: Create Additional Users

​6.1 Navigate to Users

​6.2 Create an Editor User

​6.3 Create a Viewer User

​Step 7: Make Your First API Request

​7.1 Get Your Access Token

​7.2 Test the API with curl

​7.3 Create a Record via API

​7.4 Explore the Interactive API Docs

​Step 8: Test Permissions

​8.1 Log In as Editor

​8.2 Verify Edit Capabilities

​8.3 Test Delete Restriction

​Development Commands

​Backend Commands

​Frontend Commands

​Troubleshooting

​Database Errors

​Port Conflicts

​Email Verification Problems

​API Endpoints Reference

​Common Gotchas & Tips

​Gotcha 1: Account Context in API Requests

​Gotcha 2: Collection Names Become URL Endpoints

​Gotcha 3: Built-in Hooks Auto-Set Timestamps

​Gotcha 4: Superadmin vs Admin

​Gotcha 5: Permission Caching

​Production Considerations

​Security Settings

​Database Setup

​Environment Variables

​Next Steps

Prerequisites

Step 1: Install and Start SnackBase

1.1 Clone the Repository

1.2 Install Backend Dependencies

1.3 Install Frontend Dependencies

1.4 Configure Environment

1.5 Initialize the Database

1.6 Configure Email (Optional but Recommended)

1.7 Create a Superadmin User

1.8 Start the Backend Server

1.9 Start the Frontend (New Terminal)

1.10 Access the Admin UI

Step 2: Log In to the Admin UI

2.1 Enter Your Credentials

2.2 Verify Your Email (If Required)

2.3 Welcome to the Dashboard

Step 3: Create Your First Collection

3.1 Navigate to Collections

3.2 Create a New Collection

3.3 Add Fields to Your Collection

Step 4: Add Your First Records

4.1 Navigate to Records

4.2 Create a Record

4.3 View Your Record

4.4 Add More Records

Step 5: Set Up Roles and Permissions

5.1 Navigate to Roles

5.2 Understand Default Roles

5.3 Create a New Role

5.4 Configure Permissions

5.5 Create a Read-Only Role

Step 6: Create Additional Users

6.1 Navigate to Users

6.2 Create an Editor User

6.3 Create a Viewer User

Step 7: Make Your First API Request

7.1 Get Your Access Token

7.2 Test the API with curl

7.3 Create a Record via API

7.4 Explore the Interactive API Docs

Step 8: Test Permissions

8.1 Log In as Editor

8.2 Verify Edit Capabilities

8.3 Test Delete Restriction

Development Commands

Backend Commands

Frontend Commands

Troubleshooting

Database Errors

Port Conflicts

Email Verification Problems

API Endpoints Reference

Common Gotchas & Tips

Gotcha 1: Account Context in API Requests

Gotcha 2: Collection Names Become URL Endpoints

Gotcha 3: Built-in Hooks Auto-Set Timestamps

Gotcha 4: Superadmin vs Admin

Gotcha 5: Permission Caching

Production Considerations

Security Settings

Database Setup

Environment Variables

Next Steps