Troubleshooting:Service Troubleshooting: Difference between revisions

Latest revision as of 10:44, 7 July 2026

This guide covers troubleshooting for reverse proxy services on the VPS. Public HTTPS is handled by Caddy (/etc/caddy/Caddyfile).

Common Issues

Issue: 502 Bad Gateway

Causes:

Backend not running (Docker on VPS or service on NAS)

Caddy misconfigured or not reloaded after Caddyfile change

Wrong port number

Service not accessible via VPN

Solutions:

# Test from VPS to NAS
ping 10.8.0.2
curl http://10.8.0.2:PORT_NUMBER

# Test VPS-local Docker service
curl -sI http://127.0.0.1:PORT_NUMBER

# Check Caddy logs
journalctl -u caddy -n 50

# Check if service is listening (from Synology NAS or via SSH)
netstat -tlnp | grep PORT_NUMBER

Issue: SSL Certificate Failed

Causes:

DNS not pointing to VPS

Port 80 blocked

Rate limiting from Let's Encrypt

Solutions:

# Check DNS
nslookup newservice.jb-vpn.uk

# Verify port 80 is open
curl -I http://newservice.jb-vpn.uk

# Check firewall
sudo iptables -L -n -v | grep 80

# Validate Caddy config
caddy validate --config /etc/caddy/Caddyfile

Issue: Service Not Loading

Causes:

Wrong upstream URL in Caddyfile

Missing proxy headers

Service requires specific path

Solutions:

Check Caddy: journalctl -u caddy -n 50

Verify backend directly: curl http://127.0.0.1:PORT (VPS) or curl http://10.8.0.2:PORT (NAS via VPN)

Validate and reload: caddy validate --config /etc/caddy/Caddyfile && systemctl reload caddy

Issue: Connection Timeout

Causes:

VPN tunnel down

Service not accessible

Firewall blocking

Solutions:

# Check VPN
ip addr show tun0
ping 10.8.0.2
cat /var/log/openvpn-status.log

# Check routing
ip route | grep 10.8.0.0

# Test connectivity
curl -v http://10.8.0.2:PORT_NUMBER

Diagnostic Commands

# Caddy
caddy validate --config /etc/caddy/Caddyfile
systemctl status caddy
systemctl reload caddy
journalctl -u caddy -n 50

# OpenVPN (for NAS-backed services)
systemctl status openvpn-server@server.service
ip addr show tun0
cat /var/log/openvpn-status.log

# Test public endpoint
curl -I https://service.jb-vpn.uk

# Docker stacks on VPS
cd /var/www/wiki.jb && docker compose ps

Service-specific guides

Plex: Troubleshooting:Plex Troubleshooting — auth, custom access URLs, Caddy pitfalls

Nginx (legacy): Troubleshooting:Nginx Troubleshooting — host/WebApp internal nginx only

@@ Line 1: / Line 1: @@
-= Service Troubleshooting =
+This guide covers troubleshooting for reverse proxy services on the VPS. Public HTTPS is handled by '''Caddy''' (<code>/etc/caddy/Caddyfile</code>).
-This guide covers troubleshooting for reverse proxy services.
 == Common Issues ==
@@ Line 8: / Line 6: @@
 '''Causes''':
-'' Service not running on Synology NAS
+* Backend not running (Docker on VPS or service on NAS)
-'' Wrong port number
-'' Service not accessible via VPN
+* Caddy misconfigured or not reloaded after Caddyfile change
+* Wrong port number
+* Service not accessible via VPN
 '''Solutions''':
 <pre class="lang-bash">
-= Test from VPS to NAS =
+# Test from VPS to NAS
 ping 10.8.0.2
 curl http://10.8.0.2:PORT_NUMBER
-= Check if service is listening =
+# Test VPS-local Docker service
-= (from Synology NAS or via SSH) =
+curl -sI http://127.0.0.1:PORT_NUMBER
+# Check Caddy logs
+journalctl -u caddy -n 50
+# Check if service is listening (from Synology NAS or via SSH)
 netstat -tlnp | grep PORT_NUMBER
 </pre>
@@ Line 26: / Line 33: @@
 '''Causes''':
-'' DNS not pointing to VPS
+* DNS not pointing to VPS
-'' Port 80 blocked
-'' Rate limiting from Let's Encrypt
+* Port 80 blocked
+* Rate limiting from Let's Encrypt
 '''Solutions''':
 <pre class="lang-bash">
-= Check DNS =
+# Check DNS
 nslookup newservice.jb-vpn.uk
-= Verify port 80 is open =
+# Verify port 80 is open
 curl -I http://newservice.jb-vpn.uk
-= Check firewall =
+# Check firewall
 sudo iptables -L -n -v | grep 80
+# Validate Caddy config
+caddy validate --config /etc/caddy/Caddyfile
 </pre>
@@ Line 45: / Line 57: @@
 '''Causes''':
-'' Wrong proxy_pass URL
+* Wrong upstream URL in Caddyfile
-'' Missing headers
-'' Service requires specific path
+* Missing proxy headers
+* Service requires specific path
 '''Solutions''':
-'' Check nginx error log: <code>tail -f /var/log/nginx/error.log</code>
+* Check Caddy: <code>journalctl -u caddy -n 50</code>
-'' Verify service works directly: <code>curl http://10.8.0.2:PORT</code>
-'' Test with different proxy_pass formats
+* Verify backend directly: <code>curl http://127.0.0.1:PORT</code> (VPS) or <code>curl http://10.8.0.2:PORT</code> (NAS via VPN)
+* Validate and reload: <code>caddy validate --config /etc/caddy/Caddyfile && systemctl reload caddy</code>
 === Issue: Connection Timeout ===
 '''Causes''':
-'' VPN tunnel down
+* VPN tunnel down
-'' Service not accessible
-'' Firewall blocking
+* Service not accessible
+* Firewall blocking
 '''Solutions''':
 <pre class="lang-bash">
-= Check VPN =
+# Check VPN
 ip addr show tun0
 ping 10.8.0.2
+cat /var/log/openvpn-status.log
-= Check routing =
+# Check routing
-ip route | grep 10.8.0.2
+ip route | grep 10.8.0.0
-= Test connectivity =
+# Test connectivity
 curl -v http://10.8.0.2:PORT_NUMBER
 </pre>
@@ Line 77: / Line 96: @@
 <pre class="lang-bash">
-= Check service status =
+# Caddy
-systemctl status nginx
+caddy validate --config /etc/caddy/Caddyfile
+systemctl status caddy
+systemctl reload caddy
+journalctl -u caddy -n 50
-= Test nginx configuration =
+# OpenVPN (for NAS-backed services)
-nginx -t
+systemctl status openvpn-server@server.service
+ip addr show tun0
+cat /var/log/openvpn-status.log
-= View error logs =
+# Test public endpoint
-tail -f /var/log/nginx/error.log
+curl -I https://service.jb-vpn.uk
-= View access logs =
+# Docker stacks on VPS
-tail -f /var/log/nginx/access.log
+cd /var/www/wiki.jb && docker compose ps
+</pre>
-= Check SSL certificates =
+== Service-specific guides ==
-certbot certificates
-= Test service directly =
+* '''Plex''': [[Troubleshooting:Plex Troubleshooting|Troubleshooting:Plex Troubleshooting]] — auth, custom access URLs, Caddy pitfalls
-curl -I https://service.jb-vpn.uk
-</pre>
+* '''Nginx (legacy)''': [[Documentation:Nginx-Troubleshooting|Troubleshooting:Nginx Troubleshooting]] — host/WebApp internal nginx only
 == Related Documentation ==
-'' [Adding Services](index.md) - Service configuration
+* [[Services:Current Services|Services:Current Services]] — service inventory
-* [System Overview](index.md) - System architecture
+* [[Documentation:Components|System:Components]] — Caddy, VPN, Docker components
 [[Category:Documentation]]
 [[Category:Documentation/Troubleshooting]]