Initial Commit
This commit is contained in:
@@ -0,0 +1,218 @@
|
||||
# Troubleshooting: musicassistant-app.hanold.online
|
||||
|
||||
## Problem Analysis
|
||||
|
||||
When connecting to `https://musicassistant-app.hanold.online`, you're getting an **NSURLErrorDomain** error. This typically indicates:
|
||||
|
||||
1. **DNS Resolution Failed** - Domain cannot be resolved to an IP
|
||||
2. **Server Not Reachable** - Domain exists but server is offline/unreachable
|
||||
3. **Firewall/Network Blocking** - Network is blocking the connection
|
||||
4. **Port Not Open** - Port 8095 might not be accessible from the internet
|
||||
|
||||
## Diagnostic Steps
|
||||
|
||||
### 1. Verify Domain Resolution
|
||||
|
||||
**On Mac/Linux:**
|
||||
```bash
|
||||
# Check if domain resolves
|
||||
nslookup musicassistant-app.hanold.online
|
||||
|
||||
# Check connectivity
|
||||
ping musicassistant-app.hanold.online
|
||||
|
||||
# Test HTTPS connection
|
||||
curl -v https://musicassistant-app.hanold.online:8095
|
||||
|
||||
# Test specific endpoint
|
||||
curl -v https://musicassistant-app.hanold.online:8095/api/auth/login
|
||||
```
|
||||
|
||||
**Expected results:**
|
||||
- `nslookup` should return an IP address
|
||||
- `ping` should show responses (if ICMP is allowed)
|
||||
- `curl` should connect (even if it returns auth error)
|
||||
|
||||
### 2. Check Common Issues
|
||||
|
||||
#### Issue A: Domain Not Configured
|
||||
**Symptoms:** `nslookup` fails or returns NXDOMAIN
|
||||
|
||||
**Solutions:**
|
||||
- Verify DNS A record exists for `musicassistant-app.hanold.online`
|
||||
- Wait for DNS propagation (can take 24-48 hours)
|
||||
- Try using IP address directly: `https://YOUR_IP:8095`
|
||||
|
||||
#### Issue B: Port Not Open
|
||||
**Symptoms:** Domain resolves but connection times out
|
||||
|
||||
**Solutions:**
|
||||
- Check firewall allows port 8095
|
||||
- Verify router port forwarding is configured
|
||||
- Test with `telnet YOUR_IP 8095` or `nc -zv YOUR_IP 8095`
|
||||
|
||||
#### Issue C: SSL Certificate Issues
|
||||
**Symptoms:** Connection fails with SSL error
|
||||
|
||||
**Solutions:**
|
||||
- Verify SSL certificate is valid: `openssl s_client -connect musicassistant-app.hanold.online:8095`
|
||||
- Ensure certificate matches domain name
|
||||
- Check certificate is not expired
|
||||
|
||||
#### Issue D: Music Assistant Not Running
|
||||
**Symptoms:** Domain resolves but no response
|
||||
|
||||
**Solutions:**
|
||||
- Check Music Assistant is running: `systemctl status music-assistant`
|
||||
- Verify it's listening on all interfaces (0.0.0.0)
|
||||
- Check Music Assistant logs for errors
|
||||
|
||||
### 3. Test from Different Networks
|
||||
|
||||
Try connecting from:
|
||||
- **Mobile Data** (not WiFi) - Tests if home network is the issue
|
||||
- **Another WiFi Network** - Tests if ISP is blocking
|
||||
- **VPN** - Tests if geographic restrictions apply
|
||||
|
||||
### 4. Check Music Assistant Configuration
|
||||
|
||||
Music Assistant needs to be configured for external access:
|
||||
|
||||
**config.yaml should have:**
|
||||
```yaml
|
||||
server:
|
||||
host: 0.0.0.0 # Listen on all interfaces
|
||||
port: 8095
|
||||
ssl_certificate: /path/to/cert.pem
|
||||
ssl_key: /path/to/key.pem
|
||||
```
|
||||
|
||||
### 5. Verify Network Path
|
||||
|
||||
```bash
|
||||
# Trace route to server
|
||||
traceroute musicassistant-app.hanold.online
|
||||
|
||||
# Check if specific port is reachable
|
||||
telnet musicassistant-app.hanold.online 8095
|
||||
```
|
||||
|
||||
## Common Error Codes
|
||||
|
||||
| Error Code | Meaning | Solution |
|
||||
|------------|---------|----------|
|
||||
| -1003 | Cannot find host | DNS not resolving - check domain configuration |
|
||||
| -1004 | Cannot connect to host | Server unreachable - check firewall/port |
|
||||
| -1001 | Request timed out | Server not responding - check Music Assistant is running |
|
||||
| -1200 | Secure connection failed | SSL/TLS error - check certificate |
|
||||
| -1009 | Not connected to internet | Check device network connection |
|
||||
|
||||
## Quick Fixes
|
||||
|
||||
### Fix 1: Use IP Address Instead
|
||||
If DNS is the issue:
|
||||
```
|
||||
https://YOUR_PUBLIC_IP:8095
|
||||
```
|
||||
|
||||
### Fix 2: Use Local Access
|
||||
If on same network:
|
||||
```
|
||||
http://LOCAL_IP:8095 (e.g., http://192.168.1.100:8095)
|
||||
```
|
||||
|
||||
### Fix 3: Test with HTTP First
|
||||
Rule out SSL issues:
|
||||
```
|
||||
http://musicassistant-app.hanold.online:8095
|
||||
```
|
||||
⚠️ Only for testing! Use HTTPS in production.
|
||||
|
||||
### Fix 4: Check Port in URL
|
||||
Ensure you're including the port:
|
||||
- ✅ `https://musicassistant-app.hanold.online:8095`
|
||||
- ❌ `https://musicassistant-app.hanold.online` (will try port 443)
|
||||
|
||||
## App-Side Improvements
|
||||
|
||||
The app now provides better error messages:
|
||||
|
||||
```swift
|
||||
// DNS lookup failed
|
||||
"DNS lookup failed. Cannot resolve domain name. Check the URL."
|
||||
|
||||
// Cannot connect
|
||||
"Cannot connect to server. The server might be offline or unreachable."
|
||||
|
||||
// Timeout
|
||||
"Connection timed out. The server is taking too long to respond."
|
||||
```
|
||||
|
||||
These messages will appear in the login error alert.
|
||||
|
||||
## Recommended Setup
|
||||
|
||||
For external access to Music Assistant:
|
||||
|
||||
### Option 1: Direct Access (Simple but less secure)
|
||||
1. Configure router port forwarding: External 8095 → Internal 8095
|
||||
2. Set up Dynamic DNS (if you don't have static IP)
|
||||
3. Configure SSL certificate for domain
|
||||
4. Allow port 8095 in firewall
|
||||
|
||||
### Option 2: Reverse Proxy (Recommended)
|
||||
1. Use nginx/Caddy as reverse proxy
|
||||
2. Proxy HTTPS traffic to Music Assistant
|
||||
3. Let reverse proxy handle SSL
|
||||
4. Use standard HTTPS port 443
|
||||
|
||||
**Example nginx config:**
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name musicassistant-app.hanold.online;
|
||||
|
||||
ssl_certificate /path/to/cert.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:8095;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 3: Tailscale/WireGuard VPN (Most Secure)
|
||||
1. Set up Tailscale or WireGuard
|
||||
2. Access Music Assistant via VPN
|
||||
3. No port forwarding needed
|
||||
4. Fully encrypted end-to-end
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Domain resolves in DNS lookup
|
||||
- [ ] Server responds to ping (if enabled)
|
||||
- [ ] Port 8095 is open and accessible
|
||||
- [ ] Music Assistant is running
|
||||
- [ ] SSL certificate is valid
|
||||
- [ ] Firewall allows connections
|
||||
- [ ] Can access via web browser
|
||||
- [ ] WebSocket connections work
|
||||
|
||||
## If Still Not Working
|
||||
|
||||
1. **Check Music Assistant logs** on the server
|
||||
2. **Enable debug logging** in the iOS app (check Xcode console)
|
||||
3. **Try from web browser** first to isolate app issues
|
||||
4. **Verify with curl** to test raw HTTP connection
|
||||
5. **Check router logs** for blocked connections
|
||||
|
||||
## Contact Information
|
||||
|
||||
If you've verified all the above and it still doesn't work, the issue is likely:
|
||||
- **Server-side configuration** - Check Music Assistant setup
|
||||
- **Network infrastructure** - Check router/firewall
|
||||
- **DNS configuration** - Verify domain points to correct IP
|
||||
Reference in New Issue
Block a user