Troubleshooting

Having issues with Runtipi? This section will help you diagnose and fix common problems.

Frequently Asked Questions (FAQ)

General Questions

Q: What are the minimum requirements to run Runtipi?

A: You need a 64-bit processor, 4GB RAM minimum (8GB recommended), and 10GB free disk space. Runtipi supports x86_64 and ARM64 architectures.

Q: Can I run Runtipi on a Raspberry Pi?

A: Yes! Raspberry Pi 4 and 5 with ARM64 architecture are supported. Note that some apps may not be available on ARM.

Q: Does Runtipi work on Windows or macOS?

A: No, Runtipi requires a Linux server. You can run it in a Linux VM on Windows/macOS, but native support is not available.

Q: How do I update Runtipi?

A: Run sudo ./runtipi-cli update latest from your Runtipi directory.

Q: Will updating Runtipi break my apps?

A: Generally no, but check the release notes for breaking changes. Always backup first.

Installation questions

Q: “Permission denied” errors during installation

A: Make sure you’re running with sudo:

curl -L https://setup.runtipi.io | sudo bash

Q: Can I install Runtipi in a custom directory?

A: Yes, just cd to that directory before running the install script.

Q: Can I install apps that aren’t in the App Store?

A: You can create your own app through the web UI or use one of the community app store  repositories.

Q: Where is my app data stored?

A: All app data is in app-data/[store-slug]/[app-name]/ in your Runtipi directory.

Networking questions

Q: Can I use Runtipi behind another reverse proxy like Nginx Proxy Manager?

A: Yes, but it’s complex. Runtipi uses Traefik internally. You’d need to configure your external proxy to forward to Runtipi’s Traefik and customize your settings to free up ports.

Dashboard behind a reverse proxy or tunnel

This section applies when you access the Runtipi dashboard itself through Cloudflare Tunnel or another reverse proxy. Normal exposed app traffic is not affected by the dashboard origin check.

If authenticated dashboard actions such as starting, stopping, or updating apps fail with Invalid request origin, Traefik may not trust the proxy that forwards the request. Traefik must trust that proxy before it accepts forwarded headers like X-Forwarded-Host and X-Forwarded-Proto.

Add the proxy IP address or CIDR to runtipi/state/settings.json:

{
  "trustedProxyIps": "172.18.0.5/32"
}

Then restart Runtipi.

Find the proxy IP

If the proxy is running as a Docker container on the runtipi_tipi_main_network, list the containers on that network:

docker ps --filter network=runtipi_tipi_main_network --format "table {{.Names}}\t{{.Networks}}"

Then inspect the proxy container:

docker inspect -f '{{with index .NetworkSettings.Networks "runtipi_tipi_main_network"}}{{.IPAddress}}{{end}}' <proxy-container-name>

If the proxy is not running as a Docker container on the Runtipi network, use Traefik access logs to find the source address Traefik receives:

1. Open runtipi/traefik/traefik.yml.
2. Add JSON access logs:

accessLog:
  format: json

3. Restart only Traefik:

docker restart runtipi-reverse-proxy

4. Reproduce the Invalid request origin error once.
5. Check the Traefik logs and look for ClientAddr:

docker logs runtipi-reverse-proxy --tail 100

Use the IP part of ClientAddr as the value for trustedProxyIps, usually with a /32 suffix for a single IPv4 address.

Security questions

Q: Is it safe to expose Runtipi to the internet?

A: Only with proper security measures:

• Strong passwords (20+ characters)
• HTTPS/SSL enabled
• Firewall configured
• Regular updates
• Consider using Cloudflare tunnel instead

Q: Should I run Runtipi on a VPS?

A: It’s possible but requires extra security setup. See VPS Security. Home servers behind routers are generally more secure for beginners.

Troubleshooting Questions

Q: Runtipi uses too much disk space

A: Check app data sizes:

du -sh app-data/*

Large apps (media servers, cloud storage) can use hundreds of GB. Clean up unused data or add more storage.

Check if you have anything in the backups folder:

du -sh backups/

Q: Runtipi is using too much RAM/CPU

A: Check which apps are consuming resources:

docker stats

Some apps (media transcoding, databases) are resource-intensive. Consider upgrading hardware or stopping unused apps.

Q: “Port already in use” error

A: Another service is using that port. Find it:

sudo netstat -tulpn | grep :PORT

Either stop that service or change the app’s port in settings.

Getting Help

If you can’t find a solution here:

When Asking for Help

Please include:

• Runtipi version: sudo ./runtipi-cli version
• Operating system and version
• Docker version: docker version
• Relevant logs: sudo ./runtipi-cli debug
• Steps to reproduce the issue
• What you’ve already tried