Docker Deployment

Run TallyHub in Docker on Raspberry Pi, Linux, or any container platform

🚀 Quick Start

One-command installation for Raspberry Pi and Linux:

bash

curl -fsSL https://raw.githubusercontent.com/tallyhubpro/Tallyhub/main/install.sh | sudo bash

✅ Auto-installs Docker

✅ Pulls latest image

✅ Creates volumes

✅ Auto-restart enabled

Manual Docker Setup

Option 1: Prebuilt Image

Use the official prebuilt image from GitHub Container Registry:

1. Pull the latest image:

bash

docker pull ghcr.io/tallyhubpro/tallyhub:latest

2. Create required directories:

bash

sudo mkdir -p /opt/tallyhub/logs /opt/tallyhub/public/firmware
sudo touch /opt/tallyhub/device-storage.json /opt/tallyhub/device-assignments.json

3. Run the container:

bash

docker run -d \
  --name tallyhub \
  --restart unless-stopped \
  --network host \
  -e NODE_ENV=production \
  -e TZ=UTC \
  -v /opt/tallyhub/device-storage.json:/app/device-storage.json \
  -v /opt/tallyhub/device-assignments.json:/app/device-assignments.json \
  -v /opt/tallyhub/logs:/app/logs \
  -v /opt/tallyhub/public/firmware:/app/public/firmware:ro \
  ghcr.io/tallyhubpro/tallyhub:latest

💡 Host Networking

Using --network host is recommended on Raspberry Pi so mDNS/Bonjour and UDP device discovery work correctly.

If you can't use host networking, publish ports instead:

bash

-p 3000:3000 -p 7411:7411/udp

Option 2: Docker Compose

Build and run TallyHub locally with Docker Compose:

1. Clone the repository:

bash

git clone https://github.com/tallyhubpro/Tallyhub.git
cd Tallyhub/docker

2. Start with Docker Compose:

bash

docker compose up -d --build
docker compose logs -f

📁 Mounted Volumes

• device-storage.json - Device configurations
• device-assignments.json - Camera assignments
• logs/ - Application logs
• public/firmware - Custom firmware files (read-only)

Environment Variables

NODE_ENVdefault: development

Set to 'production' for production deployments

LOG_LEVELdefault: info

Logging level: error, warn, info, debug

PORTdefault: 3000

HTTP server port

TZdefault: UTC

Timezone for logs (e.g., America/New_York)

GITHUB_TOKENdefault: none

Optional GitHub token for firmware downloads (higher rate limits)

DISABLE_MDNSdefault: false

Set to '1' to disable mDNS advertising

🔑 GitHub Token

Optional but recommended for GitHub firmware downloads:

• Increases API rate limit from 60/hour to 5000/hour
• Enables access to private repositories
• Improves reliability for firmware updates

Add to your docker run command:

bash

-e GITHUB_TOKEN=ghp_your_token_here

Private Container Registry

If accessing a private GitHub Container Registry, authenticate first:

bash

echo YOUR_GITHUB_TOKEN | docker login ghcr.io -u YOUR_USERNAME --password-stdin

Container Management

View Logs

docker logs -f tallyhub

Stop Container

docker stop tallyhub

Start Container

docker start tallyhub

Restart Container

docker restart tallyhub

Update to Latest

docker pull ghcr.io/tallyhubpro/tallyhub:latest
docker stop tallyhub
docker rm tallyhub
# Then run the docker run command again

View Container Stats

docker stats tallyhub

Raspberry Pi Optimization

🍓 Raspberry Pi Tips

Use host networking: Required for mDNS and UDP discovery
ARM architecture: The official image supports armv7 and arm64
SD card lifespan: Logs are written to mounted volume, reducing SD card wear
Auto-start: Use --restart unless-stopped

Log Rotation

Prevent log files from filling up disk space:

bash

# Create a cron job to prune old logs
sudo crontab -e

# Add this line to run daily at 3 AM:
0 3 * * * find /opt/tallyhub/logs -name "*.log" -mtime +14 -delete

Network Configuration

Required Ports

• 3000/tcp - Web interface and API
• 7411/udp - Device discovery (UDP broadcast)

Firewall Rules

If using a firewall, allow these ports:

bash

# UFW (Ubuntu/Debian)
sudo ufw allow 3000/tcp
sudo ufw allow 7411/udp

# firewalld (CentOS/RHEL)
sudo firewall-cmd --add-port=3000/tcp --permanent
sudo firewall-cmd --add-port=7411/udp --permanent
sudo firewall-cmd --reload

Troubleshooting

⚠️ Devices not discovering hub

• Ensure host networking is enabled (--network host)
• Check firewall allows UDP port 7411
• Verify devices are on the same subnet
• Try disabling VLANs or network isolation

⚠️ Can't access web interface

• Check container is running: docker ps
• View logs: docker logs tallyhub
• Ensure port 3000 is not blocked by firewall
• Verify correct IP address (use ifconfig or ip addr)

⚠️ Container keeps restarting

• Check logs: docker logs tallyhub
• Verify volume mounts exist and have correct permissions
• Ensure Node.js version compatibility
• Check for port conflicts

⚠️ Out of disk space

• Clean old logs: find /opt/tallyhub/logs -mtime +14 -delete
• Remove unused Docker images: docker image prune -a
• Check Docker disk usage: docker system df

Next Steps