Skip to content

Initial Setup

After installing Bifolk, follow these steps to set up the application for first use.

Target Audience: System administrators, new administrators

Creating the Superuser

The superuser has full access to the Django admin interface and all data.

docker compose exec bifolk-app python manage.py createsuperuser

You will be prompted for:

  • Username: Admin username
  • Email: Admin email address
  • Password: Secure password

Loading Sample Data

For testing or demonstration purposes, load sample data:

docker compose exec bifolk-app python manage.py load_sample_data

This creates:

  • Sample organizations with different types
  • Sample users with different roles
  • Sample hives with inspections and harvest records
  • Sample queens with lineage
  • Sample operations (feeding, treatments, maintenance)
  • Sample warehouse inventory items
  • Sample configurable choices

Note

Sample data is intended for testing only. Do not load sample data on a production instance with real data.

First Login

  1. Open Bifolk at http://localhost:8000 (or your configured domain)
  2. Log in with your superuser credentials
  3. A personal organization is automatically created for you

Creating Your First Organization

  1. Go to Organizations in the sidebar
  2. Click Create Organization
  3. Fill in:
  4. Name: Organization name (e.g., "Smith Family Apiary")
  5. Type: Personal, Family, Club, Cooperative, or Commercial
  6. Description: Optional description
  7. Click Save

Inviting Members

  1. Go to the organization's detail page
  2. Click Invite Member
  3. Enter the person's email address
  4. Select their role (Owner, Admin, Member, or Viewer)
  5. Click Send Invitation

The invited person receives an email with a registration/acceptance link.

Configuring System Choices

Bifolk uses configurable choices for dropdowns like hive types, honey types, and health statuses. Default choices are created automatically, but you can customize them:

  1. Go to System > System Configuration in the sidebar (requires Admin or Owner role)
  2. Add, edit, or deactivate choices for each category

See System Configuration for details.

Configuring Authentication

Self-Registration

Control whether users can register themselves:

# In .env
ALLOW_SELF_REGISTRATION=True   # Allow open registration
ALLOW_SELF_REGISTRATION=False  # Admin-only user creation

Email Verification

Control whether email verification is required:

REQUIRE_EMAIL_VERIFICATION=True   # Require email verification
REQUIRE_EMAIL_VERIFICATION=False  # Skip verification

Two-Factor Authentication

Optionally enforce MFA:

MFA_REQUIRED=none    # Optional for all users (default)
MFA_REQUIRED=staff   # Required for staff/admin users
MFA_REQUIRED=all     # Required for all users
MFA_GRACE_PERIOD_DAYS=7  # Days to set up MFA before enforcement

Single Sign-On (OIDC)

See Configuration for OIDC setup.

Next Steps