Quick Start

Source Files

This page is generated from the following source files:

Fizzy is a Rails-based application that provides a platform for collaborative work. This guide covers the essential steps to set up, run, and test the application in a development environment.

Prerequisites and Installation

The setup process requires several command-line tools and system dependencies. The bin/setup script automates the installation of most prerequisites, checking for their presence and installing them via package managers when available.

Required CLI Tools

The setup script checks for three essential tools: gum (for terminal UI styling), mise (for Ruby version management), and gh (GitHub CLI). If any tool is missing, the script attempts to install it via pacman (Arch Linux) or brew (macOS) (bin/setup:19-62).

bash
1# Run the automated setup script
2bin/setup
3
4# Or reset the database and reseed
5bin/setup --reset

Ruby and System Packages

After installing CLI tools, the setup installs Ruby via mise and then installs required system packages. On Arch Linux, these include imagemagick, mariadb-libs, openslide, libvips, libheif, libwebp, libjxl, libraw, poppler-glib, libcgif, ffmpeg, rav1e, svt-av1, and gitleaks. On macOS, the script installs imagemagick, openslide, vips, and gitleaks (bin/setup:114-133).

The application uses Rails from the main branch, along with asset pipelines (importmap-rails, propshaft, stimulus-rails, turbo-rails) and database adapters (sqlite3, trilogy for MySQL) (Gemfile:1-22).

Database Setup

Fizzy uses SQLite as the default database adapter and supports MySQL as an alternative. The database configuration dynamically selects the appropriate adapter based on the DATABASE_ADAPTER environment variable.

Automatic Database Preparation

The setup script handles database creation and seeding automatically. When run without arguments, it prepares the database and seeds it if no data exists. With the --reset flag, it drops and recreates the database with fresh seed data (bin/setup:146-154).

bash
1# Standard setup (prepare + seed if empty)
2bin/setup
3
4# Full reset (drop, create, migrate, seed)
5bin/setup --reset

Database Adapter Configuration

The database configuration file loads different YAML files based on the adapter type. For SaaS mode, it loads a separate configuration; otherwise, it uses config/database.{adapter}.yml (config/database.yml:1-9).

To use MySQL instead of SQLite:

bash
1DATABASE_ADAPTER=mysql bin/setup --reset

Seed Data Structure

The seed file creates development accounts with a DSL for defining seed accounts. It includes helper methods for creating tenants, users, and boards. The default seeds create three accounts: "cleanslate", "37signals", and "honcho" (db/seeds.rb:1-32).

The default login identity uses the email david@example.com with staff privileges (db/seeds.rb:16-17).

Running the Development Server

The development server runs on port 3006 by default. The bin/dev script handles server startup with optional features for remote access and push notifications.

Basic Server Startup

bash
1bin/dev

The server binds to 0.0.0.0 on port 3006 (bin/dev:1-20). After starting, the application is accessible at http://fizzy.localhost:3006 (docs/development.md:12-21).

To log in to the development environment, use the email david@example.com. The verification code appears in the browser console (docs/development.md:18-20).

Optional Tailscale Integration

For remote access, the server supports Tailscale integration with the --tailscale flag. This creates a secure HTTPS endpoint using Tailscale's serve feature (bin/dev:38-66).

bash
1# Start with Tailscale remote access
2bin/dev --tailscale

When Tailscale is enabled, the script displays a login URL with the Tailscale hostname and port 43006 (prefixed with 4 to the base port) (bin/dev:50-61).

Running Tests

Fizzy provides two test commands: one for fast unit