Skip to main content

Quick Start Wizard

Welcome to Hive-Pal! This interactive guide will help you get up and running in minutes. Follow these steps to set up your beekeeping management system.

Prerequisites​

Before you begin, ensure you have:

  • Docker and Docker Compose installed (for Docker setup)
  • Node.js 22+ and PostgreSQL (for manual setup)
  • A modern web browser

Step 1: Choose Your Installation Method​

Docker Installation​

The fastest way to get started. Hive-Pal ships as a single container that serves both the API and the web app. Create a docker-compose.yaml:

services:
  app:
    image: ghcr.io/martinhrvn/hive-pal:latest
    ports:
      - '80:3000'
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://postgres:postgres@postgres:5432/beekeeper
      BETTER_AUTH_SECRET: replace_me_with_a_random_string
      BETTER_AUTH_URL: http://localhost
      FRONTEND_URL: http://localhost
      ADMIN_EMAIL: admin@example.com
      ADMIN_PASSWORD: changeme123
      STORAGE_TYPE: local
    volumes:
      - uploads:/data/uploads
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:14
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: beekeeper
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres -d beekeeper']
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:
  uploads:

Then start it:

docker compose up -d
tip

On startup the app automatically:

  • Waits for PostgreSQL to be ready
  • Runs database migrations
  • Creates the admin user from ADMIN_EMAIL / ADMIN_PASSWORD
  • Serves the web app and API on the same port

Generate BETTER_AUTH_SECRET with openssl rand -base64 32. See the Installation Guide for all options.

Step 2: Access the Application​

Once the containers are running:

  1. Open your browser and navigate to http://localhost (Docker) — or http://localhost:5173 if you used the manual/development setup.
  2. You should see the Hive-Pal landing page.
note
  • Docker: the whole app (web + API) is served on the port you mapped (80 in the example above)
  • Manual/dev: frontend on 5173, backend API on 3000
  • API documentation is available at /api-docs on the backend

Step 3: Sign In or Create an Account​

[Video: Account Registration Process - Coming Soon]

For a fresh self-hosted install, log in with the ADMIN_EMAIL / ADMIN_PASSWORD you set in the compose file. To create additional accounts:

  1. Click "Get Started" on the landing page, then "Sign Up".
  2. Enter your email and password and accept the privacy policy.
  3. Click "Create Account".

Hive-Pal supports three sign-in methods (see the Login guide):

  • Email & password — always available
  • Magic link — passwordless email sign-in (requires email to be configured)
  • Passkey — biometric or hardware-key sign-in
tip

Magic links and password resets require a mail provider (SMTP or Resend). See Configuration → Email.

Step 4: Initial Setup Wizard​

When you first log into Hive-Pal, you'll be automatically guided through a setup wizard that helps you create your first apiary and hive.

The Setup Process​

The wizard consists of four steps:

Step 1: Welcome Screen​

  • Introduction to Hive-Pal
  • Overview of what you'll set up
  • Click "Get Started" to begin

Step 2: Create Your First Apiary​

  • Apiary Name: Enter a descriptive name (e.g., "Home Garden", "Smith Farm")
  • Location: Add address or description
  • GPS Coordinates (optional): For weather integration
  • Notes (optional): Any additional information
  • The apiary is created immediately upon submission

Step 3: Add Your First Hive​

  • Hive Name/Identifier: Choose a unique name or number
  • Hive Type: Select from available options
  • Status: Set initial status (Active, Preparing, etc.)
  • Installation Date: When the hive was set up
  • The hive is automatically assigned to the apiary you just created

Step 4: Setup Complete​

  • Confirmation that your initial setup is finished
  • Click "Go to Dashboard" to start using Hive-Pal
  • You now have your first apiary with one hive ready to track!

Step 5: Explore Key Features​

Quick Actions Menu (FAB)​

The floating action button (FAB) in the bottom right corner provides quick access to three primary actions:

  • Add Inspection (Blue): Record a new hive inspection
  • Schedule Inspection (Purple): Plan future inspections
  • Add Actions (Green): Record treatments, feeding, or other management actions across multiple hives

Dashboard Overview​

Your dashboard displays:

  • Recent inspections
  • Upcoming scheduled tasks
  • Weather forecast for your apiaries
  • Quick statistics

Mobile Usage​

Hive-Pal is fully responsive and works great on mobile devices:

  • Record inspections in the field
  • Quick access to hive history
  • Offline capability (data syncs when reconnected)

What's Next?​

Now that you're set up, explore these features:

Need Help?​

Video Tutorial​

[Complete Video Walkthrough - Coming Soon]

Congratulations!

You've successfully set up Hive-Pal and are ready to manage your apiaries digitally. Happy beekeeping! 🐝