FAQ & troubleshooting

General

Is PetHealth free? Yes. It’s free and open source under the MIT License: you can use, install, modify and redistribute it, as long as you keep the copyright notice. There’s no paid plan, account or subscription.

Can I make it reachable from the internet? Please don’t. PetHealth is designed for home networks and hasn’t been through a security audit or penetration testing. To use it away from home, connect through a VPN such as WireGuard or Tailscale. See Remote access.

Is there a hosted version? No. PetHealth is self-hosted only.

Where is my data? In the folder you mount at /app/data: one SQLite database plus your uploaded files. Nothing is sent anywhere, except the reminder emails if you configure SMTP.

Does it need the internet? No. It works entirely on your local network. Email reminders only need to reach your SMTP server.

Is there a mobile app? It’s a responsive web app: open it in your phone’s browser. You can add it to your home screen from the browser menu.

Which languages are supported? English and Spanish. Each user picks theirs, and emails and the calendar follow it.

Which pets can I track? Dogs, cats, birds, rabbits, rodents, ferrets, reptiles, fish, horses and “other”.

Installation

Does it run on a Raspberry Pi / ARM? The published image is linux/amd64 only. On ARM, build it from source.

The container exits right away. Check docker logs pethealth. The usual cause is a missing JWT_SECRET (❌ JWT_SECRET no está configurado). Set it and start again.

Port 3000 is already in use. Map another host port, e.g. -p 8080:3001, and open http://localhost:8080.

I set SEED_DEMO=false but the demo pets are there. It only applies to a brand-new database. Delete the demo pets from their profiles, or remove data/ (losing everything) and start again.

I forgot my password. There’s no self-service reset yet. Whoever runs the server can set a temporary password from the command line. Replace admin with the username:

docker exec pethealth node -e "const db=require('better-sqlite3')('/app/data/pethealth.db'); const b=require('bcryptjs'); const r=db.prepare('UPDATE users SET password_hash = ?, must_change_password = 1, token_version = token_version + 1 WHERE username = ?').run(b.hashSync('Temporary-123', 10), 'admin'); console.log(r.changes ? 'Password reset' : 'User not found')"

Then sign in with Temporary-123. PetHealth will ask for a new password right away, and every other session of that user is signed out.

Reminders

I don’t get emails. Check that SMTP_HOST is set (the startup log says so), that you saved your address and ticked the box in My account, and try Send test email. Remember that emails are only sent on trigger days.

Google Calendar can’t subscribe to my calendar link. Google fetches subscriptions from its own servers on the internet, and PetHealth shouldn’t be publicly reachable. Use a calendar app that fetches the feed from your device, such as Apple Calendar or Thunderbird, on your network or through your VPN.

A vaccine still shows as overdue after I gave it. Log the new dose as a new vaccine entry with the same name and the new booster date. The latest dose is the one that counts. The same goes for parasite treatments (latest of each type) and visits (the next visit of the most recent checkup).

The dose button doesn’t show a target (“2 today”). The frequency text wasn’t recognized as daily (e.g. “as directed”, “weekly”). Use wording like Twice a day or Every 8 hours.

Data

How do I back up? Automatic snapshots go to data/backups/. For a full backup, copy the whole data/ folder. See Backups & upgrades.

Can I move a pet to another server or person? Yes: Export pet (ZIP) on the profile, then Import on the other dashboard.

Can two people manage the same pet? Yes, with Sharing: view-only or edit access per pet.