littleshop/TROUBLESHOOTING.md

# LittleShop Troubleshooting Guide

## Common Issues and Solutions

### 🔴 HTTP 500 Error on Login

#### Symptoms
- Login page loads (HTTP 200)
- Submitting credentials returns HTTP 500
- Error: "Request reached the end of the middleware pipeline"

#### Root Causes & Fixes

##### 1. **JWT Key Configuration Issue**
**Problem**: JWT key environment variable name mismatch or key too short

**Error Message**:
```
IDX10720: Unable to create KeyedHashAlgorithm for algorithm 'http://www.w3.org/2001/04/xmldsig-more#hmac-sha256',
the key size must be greater than: '256' bits, key has '136' bits.
```

**Solution**:
```bash
# CORRECT - Use Jwt__Key (double underscore)
-e Jwt__Key="ThisIsAVeryLongSecretKeyThatIsDefinitelyLongerThan32BytesForSure123456789ABCDEF"

# WRONG - These won't work
-e JWT_SECRET_KEY="..."  # Wrong variable name
-e Jwt_Key="..."          # Single underscore
-e Jwt__Key="shortkey"    # Key too short (< 32 bytes)
```

##### 2. **Parameter Case Sensitivity**
**Problem**: Form sends lowercase but method expected uppercase

**Solution**: Already fixed in code - Login method now accepts both cases:
```csharp
public async Task<IActionResult> Login(string Username, string Password)
{
    var username = Username?.ToLowerInvariant();
    var password = Password;
    // ...
}
```

##### 3. **Port Configuration Issue**
**Problem**: App listening on wrong port

**Solution**:
```bash
# CORRECT
-e ASPNETCORE_URLS="http://+:8080"

# WRONG
-e ASPNETCORE_HTTP_PORTS=8080  # This doesn't work
```

---

### 🔴 Container Shows "Unhealthy"

#### Symptoms
- Container running but marked as unhealthy
- Health check failing

#### Solution
1. The health check includes database check which can timeout during initialization
2. App still works even if marked unhealthy
3. To disable health check issues, run without health check or increase timeout

---

### 🔴 Database Permission Errors

#### Symptoms
- SQLite Error 8: attempt to write a readonly database
- Cannot create or update database

#### Solution
```bash
# Database MUST be owned by UID 1654
sudo chown -R 1654:1654 /opt/littleshop/data/
```

---

### 🔴 Network Connectivity Issues

#### Symptoms
- Containers can't communicate
- SilverPay API unreachable
- "Name or service not known" errors

#### Solution
```bash
# All containers must be on littleshop-network
docker network connect littleshop-network littleshop-admin
docker network connect littleshop-network silverpay-api
docker network connect littleshop-network nginx-proxy-manager
```

---

### 🔴 Anti-forgery Token Validation Errors

#### Symptoms
- 400 Bad Request on form submissions
- CSRF token validation failures

#### Current Status
- Anti-forgery validation is temporarily disabled on login
- This is noted in the code: `// [ValidateAntiForgeryToken] // Temporarily disabled for HTTPS proxy issue`

---

## Quick Diagnostics

### Check Container Status
```bash
docker ps --format "table {{.Names}}\t{{.Status}}" | grep littleshop
```

### Check Logs for Errors
```bash
docker logs littleshop-admin --tail 50 | grep -E "Exception|ERROR|fail"
```

### Test Login Locally
```bash
docker exec littleshop-admin curl -X POST http://localhost:8080/Admin/Account/Login \
  -d "Username=admin&Password=admin" \
  -o /dev/null -w "Status: %{http_code}\n"
```

### Check Environment Variables
```bash
docker exec littleshop-admin printenv | grep -E "Jwt|ASPNETCORE"
```

---

## Recovery Procedures

### Complete Reset
```bash
# Stop everything
docker stop littleshop-admin
docker rm littleshop-admin

# Clean up
sudo rm -rf /opt/littleshop/data/*

# Fix permissions
sudo mkdir -p /opt/littleshop/{data,logs,uploads}
sudo chown -R 1654:1654 /opt/littleshop/data/

# Redeploy
./deploy-littleshop.sh
```

### Emergency Development Mode
To see detailed errors:
```bash
docker run -d \
  --name littleshop-admin \
  --network littleshop-network \
  -p 127.0.0.1:5100:8080 \
  -v /opt/littleshop/data:/app/data \
  -e ASPNETCORE_ENVIRONMENT=Development \
  -e ASPNETCORE_URLS="http://+:8080" \
  -e ConnectionStrings__DefaultConnection="Data Source=/app/data/littleshop-production.db" \
  -e Jwt__Key="ThisIsAVeryLongSecretKeyThatIsDefinitelyLongerThan32BytesForSure123456789ABCDEF" \
  littleshop:latest
```

---

## Critical Configuration Points

### Must-Have Environment Variables
```
ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://+:8080  # NOT HTTP_PORTS!
Jwt__Key=[minimum 32 bytes]    # Double underscore!
ConnectionStrings__DefaultConnection=Data Source=/app/data/littleshop-production.db
```

### Required Docker Network
```
littleshop-network (external)
```

### Required Permissions
```
/opt/littleshop/data: UID 1654
/opt/littleshop/logs: UID 1654
/opt/littleshop/uploads: UID 1654
```