Skip to content

Admin Guide

Welcome to the Bifolk administrator documentation. This section provides guides for installing, configuring, and managing Bifolk.

Target Audience: Application administrators, organization owners, system administrators

Installation & Deployment

Guide Purpose
Installation Docker-based installation
Initial Setup First superuser, sample data
Configuration Environment variables and settings
Docker Secrets Secure configuration management
Podman Deployment Podman + systemd Quadlets deployment
Docker Registry Deploy from GitLab Container Registry
Useful Commands Docker and Django commands
Upgrading Upgrade procedures
Backup & Restore Data backup and restoration
Monitoring Health checks and system monitoring
Troubleshooting Common issues and solutions

Application Administration

Guide Purpose
User Management Manage user accounts and profiles
Organization Management Create organizations, invite members
Permissions & Roles Role-based access control
System Configuration Configurable choices (hive types, honey types)
Data Management Import/export organization data
Maintenance System monitoring and maintenance

Administrator Roles

Bifolk has two types of administrators:

Django Superuser (System Administrator)

  • Full access to Django admin interface (/admin/)
  • Manage all organizations and users
  • Configure system-wide settings (global configurable choices)
  • Access to all data across all organizations

Use case: Technical administrators, system managers

Organization Owner (Application Administrator)

  • Full control over their organization
  • Manage organization members and invitations
  • Assign roles (Owner, Admin, Member, Viewer)
  • Configure organization settings (colors, date format, numbering schemes)
  • Export and import organization data

Use case: Beekeeping cooperative leaders, family organizers, club presidents

Common Admin Workflows

First-Time Setup

  1. Install Bifolk using Docker
  2. Create superuser account
  3. Configure environment
  4. Load sample data (optional, for testing)
  5. Create first organization

Adding a New Organization

  1. Organization leader registers an account (or admin creates one)
  2. Leader creates an organization with the appropriate type
  3. Leader invites members via email
  4. Members accept invitations and receive their roles
  5. Members begin adding hives and data

Regular Maintenance

Permission Overview

Bifolk uses a hierarchical permission system:

Action Owner Admin Member Viewer
View resources ✅ ✅ ✅ ✅
Create resources ✅ ✅ ✅ ❌
Edit own resources ✅ ✅ ✅ ❌
Edit all resources ✅ ✅ ❌ ❌
Delete resources ✅ ✅ ❌ ❌
Manage members ✅ ✅ ❌ ❌
Change org settings ✅ ✅ ❌ ❌
Delete organization ✅ ❌ ❌ ❌
Export/import data ✅ ✅ ❌ ❌

See Permissions & Roles for complete details.

Security Best Practices

  • Use strong passwords for all accounts
  • Limit superuser access to essential staff
  • Use Docker Secrets for sensitive configuration in production
  • Enable HTTPS via a reverse proxy
  • Regularly review organization memberships and remove departed members
  • Keep Bifolk updated to receive security fixes
  • Perform regular backups