Deploying Hive-Pal

Introduction

Hive-Pal is a comprehensive, mobile-first beekeeping management application designed to help beekeepers track their hives, record inspections, and monitor colony health. Built for both hobby and commercial beekeepers, Hive-Pal provides an intuitive interface for managing apiaries of any size.

Built with a modern tech stack featuring NestJS backend and React frontend, Hive-Pal stores all your beekeeping data securely and allows access from any device. The application supports multiple apiaries, detailed inspection logging, and health tracking to help maintain thriving bee colonies.

Key highlights of Hive-Pal:

• Mobile-First Design: Optimized for use in the field on phones and tablets
• Hive Management: Track multiple hives across different apiaries
• Inspection Logging: Record detailed inspection notes and observations
• Colony Health: Monitor queen status, brood patterns, and disease indicators
• Treatment Tracking: Log treatments and medications
• Weather Integration: Correlate weather with hive activity
• Photo Attachments: Add photos to inspection records
• Data Export: Export your data for analysis

This guide walks through deploying Hive-Pal on Klutch.sh using Docker, setting up your first apiary, and managing your hives.

Prerequisites

Before deploying Hive-Pal on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Hive-Pal configuration
• A PostgreSQL database (can be deployed separately on Klutch.sh)
• Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository with the following structure:

hive-pal-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile for Hive-Pal:

FROM node:18-alpine AS builder

WORKDIR /app

# Clone the repository
RUN apk add --no-cache git && \
    git clone https://github.com/martinhrvn/hive-pal.git .

# Install dependencies and build
RUN npm ci && npm run build

# Production image
FROM node:18-alpine

WORKDIR /app

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./

# Environment variables
ENV NODE_ENV=production
ENV DATABASE_URL=${DATABASE_URL}
ENV ADMIN_EMAIL=${ADMIN_EMAIL}
ENV ADMIN_PASSWORD=${ADMIN_PASSWORD}

EXPOSE 3000

CMD ["npm", "run", "start:prod"]

Using Docker Compose Configuration

Alternatively, create a simpler setup:

FROM node:18-alpine

WORKDIR /app

# Clone and build
RUN apk add --no-cache git && \
    git clone --depth 1 https://github.com/martinhrvn/hive-pal.git . && \
    npm ci && \
    npm run build

ENV NODE_ENV=production
ENV DATABASE_URL=${DATABASE_URL}

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

CMD ["npm", "run", "start:prod"]

Environment Variables Reference

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
ADMIN_EMAIL	Yes	Initial admin account email
ADMIN_PASSWORD	Yes	Initial admin account password
API_URL	No	Internal API URL for frontend
FRONTEND_URL	No	Public frontend URL
SMTP_HOST	No	SMTP server for notifications
SMTP_PORT	No	SMTP port
SMTP_USER	No	SMTP username
SMTP_PASS	No	SMTP password
FROM_EMAIL	No	Sender email address

Deploying Hive-Pal on Klutch.sh

Deploy PostgreSQL Database

First, deploy a PostgreSQL database on Klutch.sh:

• Create a new PostgreSQL app with persistent storage
• Note the connection string for configuration

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Hive-Pal deployment configuration"
git remote add origin https://github.com/yourusername/hive-pal-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “hive-pal” or “beekeeping”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Hive-Pal repository.

Configure HTTP Traffic

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Configure the following environment variables:

Variable	Value
DATABASE_URL	postgresql://user:pass@your-postgres-app:5432/hivepal
ADMIN_EMAIL	Your admin email
ADMIN_PASSWORD	A secure admin password
FRONTEND_URL	https://your-app-name.klutch.sh

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/app/uploads	10 GB	Photo and file uploads

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start Hive-Pal with HTTPS enabled.

Access Hive-Pal

Once deployment completes, access your Hive-Pal instance at https://your-app-name.klutch.sh. Log in with your configured admin credentials.

Using Hive-Pal

Setting Up Your First Apiary

1. Log in with your admin credentials
2. Navigate to Apiaries
3. Click Add Apiary
4. Enter location details and name
5. Save your apiary

Adding Hives

1. Select your apiary
2. Click Add Hive
3. Enter hive details:
   • Name or number
   • Type (Langstroth, Top Bar, etc.)
   • Installation date
   • Queen information
4. Save the hive

Recording Inspections

1. Select a hive
2. Click New Inspection
3. Record observations:
   • Queen spotted/status
   • Brood pattern
   • Population estimate
   • Food stores
   • Disease signs
   • Weather conditions
4. Add photos if desired
5. Save inspection

Tracking Treatments

1. Select a hive
2. Navigate to Treatments
3. Add treatment records:
   • Treatment type
   • Product used
   • Dosage
   • Application date
   • Follow-up date

Inspection Checklist

Use the built-in checklist during inspections:

• Queen seen or eggs present
• Brood pattern healthy
• Adequate food stores
• No signs of disease
• No pest issues
• Room for expansion
• Equipment in good condition

Best Practices

Regular Inspections

• Inspect every 7-10 days during active season
• Record detailed notes for each visit
• Take photos of unusual findings

Data Consistency

• Use consistent terminology
• Rate conditions on same scale
• Complete all relevant fields

Backup Strategy

• Export data periodically
• Keep backups of photos
• Document important observations

Troubleshooting

Cannot Log In

• Verify admin credentials are correct
• Check database connection
• Review application logs

Photos Not Uploading

• Check file size limits
• Verify upload directory permissions
• Ensure sufficient storage space

Database Connection Issues

• Verify PostgreSQL is running
• Check connection string format
• Ensure database exists

Additional Resources

• Hive-Pal GitHub Repository
• Hive-Pal Website
• Hive-Pal Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Hive-Pal on Klutch.sh provides a comprehensive beekeeping management solution accessible from any device. The mobile-first design makes it perfect for recording inspections in the field, while the web interface enables detailed analysis and planning. With persistent storage for your beekeeping data and photos, Hive-Pal helps you maintain healthy, thriving colonies through better record-keeping and observation tracking.