Skip to main content

​
Installation Issues

Symptoms: docker ps shows no running containersSolutions:
  1. Check Docker is running: 
    sudo systemctl status docker  # Linux
# or check Docker Desktop is running on macOS
  2. View container logs: 
    docker logs <container-name>
  3. Check for port conflicts: 
    sudo lsof -i :443  # Check if port 443 is in use
sudo lsof -i :8081 # Check if port 8081 is in use
  4. Restart Docker: 
    sudo systemctl restart docker  # Linux
# or restart Docker Desktop on macOS
Ubuntu/Debian:
sudo apt-get update
sudo apt-get install --fix-missing build-essential libusb-1.0-0-dev gcc pkg-config
macOS:
# Make sure Homebrew is up to date
brew update
brew doctor
brew install libusb pkg-config
Solution: Make the script executable
chmod +x install.sh
./install.sh

​
Thermostat Flashing Issues

Try these steps in order:
  1. Boot device on backplate first - Connect to wall mount and let it fully boot to home screen
  2. Remove from wall - Once booted, remove from backplate
  3. Connect USB - Use data-capable cable (not charge-only)
  4. Charge battery - Ensure >50% battery
  5. Reboot - Hold display for 10-15 seconds
See DFU Mode Troubleshooting for more details
Common issues:
  • Contacts not held long enough - Keep bridging until USB connects
  • Wrong contacts bridged - Double-check the image in the guide
  • Battery disconnected - Device won’t boot without battery
  • Screen still on - Make sure screen is off before bridging
Solution: Try multiple times, ensuring:
  • Battery is connected
  • Screen is off
  • Installer is waiting
  • Bridge contacts, THEN connect USB while holding bridge
Linux:
  1. Check USB permissions: 
    sudo ./install.sh
  2. Add udev rules: 
    echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="0451", MODE="0666"' | sudo tee /etc/udev/rules.d/99-omap.rules
sudo udevadm control --reload-rules
macOS:
  • Grant USB permissions in System Preferences → Security & Privacy
Both:
  • Try different USB cable (must be data-capable)
  • Try different USB port

​
Server Connection Issues

Check:
  1. API server is running: 
    docker ps | grep api
curl http://localhost:443  # Should respond
  2. Firewall allows connections: 
    sudo ufw allow 443  # Linux
sudo ufw allow 8081
  3. Port forwarding configured (if remote access):
    • Check router settings
    • Verify ports 443 and 8081 are forwarded to your server
  4. DNS resolves correctly (if using domain): 
    nslookup your-domain.com
  5. Thermostat can reach server:
    • Check WiFi connection on thermostat
    • Verify thermostat is on same network (for local-only setup)
Check .env.local configuration:
cd frontend
cat .env.local
Make sure:
  • VITE_API_URL points to your API server (e.g., http://192.168.1.100:8081)
  • VITE_CONVEX_URL has your Convex backend URL
  • All required environment variables are set
Test API connection manually:
curl http://your-server-ip:8081/api/devices
Restart frontend:
cd frontend
npm run dev
Self-signed certificates: If using self-signed certs, browsers will warn. You can:
  • Use Let’s Encrypt for free valid certificates
  • Accept the browser warning (not recommended for production)
Let’s Encrypt setup:
sudo apt-get install certbot
sudo certbot certonly --standalone -d your-domain.com
Then configure your server to use the certificates in /etc/letsencrypt/live/your-domain.com/

​
Docker Issues

View logs to see why:
docker logs <container-name>
Common causes:
  • Port already in use
  • Missing environment variables
  • Insufficient resources (RAM/CPU)
  • Database connection failed
Check resource usage:
docker stats
Check port mappings:
docker ps
Look for 0.0.0.0:443->443/tcp and 0.0.0.0:8081->8081/tcpIf ports aren’t mapped, recreate containers with proper port mapping:
docker run -p 443:443 -p 8081:8081 ...
Check Docker disk usage:
docker system df
Clean up unused resources:
docker system prune -a
docker volume prune
Warning: This will remove all stopped containers and unused images

​
Database Issues

Check container status:
docker ps | grep convex
docker logs <convex-container-id>
Restart Convex container:
docker restart <convex-container-id>
Check connection from API server:
  • Verify CONVEX_URL environment variable in API container
  • Test connection manually from API container
Check volume mounts:
docker inspect <convex-container-id> | grep Mounts
Data should be persisted in a Docker volume or bind mountBackup important data:
docker cp <container-id>:/data ./backup

​
Frontend Issues

Clear npm cache:
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
Try different Node version:
# Using nvm
nvm install 18
nvm use 18
npm install
Check for errors:
npm run build
Common issues:
  • Missing environment variables in .env.local
  • TypeScript errors
  • Dependency conflicts
Clean build:
rm -rf dist node_modules
npm install
npm run build
Restart dev server:
# Kill the dev server (Ctrl+C)
npm run dev
Check Vite config:
  • Make sure vite.config.ts has proper server settings
  • Try different port if 5173 is in use

​
Network & Remote Access

Check these in order:
  1. Port forwarding configured:
    • Log into your router
    • Forward ports 443, 8081 to your server’s local IP
    • Verify forwards are active
  2. Firewall allows traffic: 
    sudo ufw status
sudo ufw allow 443
sudo ufw allow 8081
  3. Public IP correct: 
    curl ifconfig.me  # Shows your public IP
  4. Dynamic DNS working (if using DDNS):
    • Verify DNS record points to current IP
    • Check DDNS client is running and updating
  5. ISP not blocking ports:
    • Some ISPs block port 443/80
    • Try alternative ports or contact ISP
Check certificate:
sudo certbot certificates
Renew if expired:
sudo certbot renew
Test HTTPS endpoint:
curl -k https://your-domain.com  # -k skips cert validation
Common issues:
  • Certificate not installed correctly
  • Server not configured for HTTPS
  • Port 443 not open
  • Domain doesn’t match certificate

​
Performance Issues

Check resource usage:
top
docker stats
df -h  # Check disk space
Solutions:
  • Allocate more resources to Docker
  • Optimize database queries
  • Reduce logging verbosity
  • Use faster storage (SSD vs HDD)
Check which container is using memory:
docker stats
Limit container memory:
docker update --memory="512m" <container-id>
Restart containers to free memory:
docker restart $(docker ps -q)

​
Still Having Issues?

Join Discord

Ask the self-hosting community for help

GitHub Issues

Report bugs or check existing issues

Check Logs

Always check Docker logs first:
docker logs <container-name>

Hosted Service

Consider using the hosted service if self-hosting is too complex