Release: v0.1.0-alpha

docs/troubleshooting.md

@@ -0,0 +1,215 @@
+# Troubleshooting
+
+Common issues and solutions for Keywarden.
+
+## Startup Issues
+
+### "Failed to initialize database"
+
+**Cause**: SQLite database file cannot be created or accessed.
+
+**Solutions**:
+- Check that the `/data` directory exists and is writable
+- Verify the `KEYWARDEN_DB_PATH` environment variable
+- In Docker: ensure the volume is correctly mounted and the `keywarden` user has write access
+
+### "Failed to create directory"
+
+**Cause**: Data directories (`/data`, `/data/keys`, `/data/master`) cannot be created.
+
+**Solutions**:
+- Check filesystem permissions
+- In Docker: the container runs as user `keywarden` — ensure the volume has correct ownership
+
+### Initial Password Not Showing
+
+**Cause**: The initial owner password is only printed on the **first startup** when no users exist.
+
+**Solutions**:
+- Check the very first startup logs: `docker compose logs keywarden`
+- If you missed the password, delete the database and restart to trigger a fresh setup:
+  ```bash
+  docker compose down
+  docker volume rm keywarden_keywarden_data
+  docker compose up -d
+  docker compose logs keywarden
+  ```
+
+## Login Issues
+
+### "Invalid username or password"
+
+- Verify the username (case-sensitive)
+- Check for typos in the password
+- If this is the initial login, find the auto-generated password in the startup logs
+
+### "Account is temporarily locked"
+
+**Cause**: Too many failed login attempts.
+
+**Solutions**:
+- Wait for the lockout period to expire (default: 15 minutes)
+- Ask an administrator to unlock the account from the user management page
+- If you're the only owner: wait for the lockout to expire, or delete and recreate the database
+
+### MFA Code Invalid
+
+- Verify your authenticator app has the correct time (TOTP is time-based)
+- Allow ±30 seconds of clock skew
+- If you lost your MFA device, an admin with database access will need to manually disable MFA
+
+### "Forbidden – invalid or missing CSRF token"
+
+**Cause**: CSRF token mismatch. This can happen if:
+- Your session expired and you submitted a form on a stale page
+- Cookies are blocked by your browser
+- A proxy is stripping or modifying cookies
+
+**Solutions**:
+- Refresh the page and try again
+- Clear your browser cookies for the Keywarden domain
+- Ensure cookies are not being blocked
+
+## SSH Deployment Issues
+
+### "System master key not available"
+
+**Cause**: The system master key is missing or corrupted in the settings table.
+
+**Solutions**:
+- Check the startup logs for the master key output
+- Navigate to Admin Settings and view the master key
+- If corrupted, regenerate the master key (owner only)
+
+### "Connection failed" / "Cannot reach server"
+
+**Cause**: Keywarden cannot establish a TCP connection to the target server.
+
+**Solutions**:
+- Verify the server hostname and port
+- Use the **Connection Test** feature to check TCP connectivity
+- Ensure the Keywarden container can reach the server's network
+- Check firewall rules on both sides
+
+### "SSH authentication failed"
+
+**Cause**: The system master key is not authorized on the target server.
+
+**Solutions**:
+1. Get the master public key from Admin Settings or startup logs
+2. Add it to the target server:
+   ```bash
+   echo "<master-public-key>" >> /root/.ssh/authorized_keys
+   chmod 600 /root/.ssh/authorized_keys
+   ```
+3. Ensure the server's SSH daemon accepts public key authentication
+4. Use the **Auth Test** feature to verify
+5. If using a non-root admin user on the target server, ensure that user has permissions to manage `authorized_keys` for other users
+
+### "Failed to create system user"
+
+**Cause**: The `useradd` command failed on the target server.
+
+**Solutions**:
+- Verify the server's admin user has sufficient privileges (root or sudo)
+- Check if the username conflicts with an existing user
+- Review the server's `/var/log/auth.log` for details
+
+### "Failed to deploy key for user"
+
+**Cause**: Key deployment to a specific system user failed.
+
+**Solutions**:
+- Verify the system user exists (or enable "Create User" in the assignment)
+- Check directory permissions on the target server
+- Ensure the admin user can write to other users' `.ssh` directories
+
+## Email Issues
+
+### "Email is not configured"
+
+**Cause**: `KEYWARDEN_SMTP_HOST` is not set.
+
+**Solution**: Configure SMTP settings in the `.env` file. See [Email Configuration](email.md).
+
+### SMTP Connection Errors
+
+- Verify the SMTP host, port, and credentials
+- Check if the Docker container can reach the SMTP server
+- Try different TLS settings (`KEYWARDEN_SMTP_TLS=true/false`)
+- For port 465, ensure implicit TLS is supported by the server
+- Check if the SMTP server requires app-specific passwords
+
+### Invitation Emails Not Arriving
+
+- Verify the recipient's email address
+- Check spam/junk folders
+- Review application logs for SMTP errors (`KEYWARDEN_LOG_LEVEL=DEBUG`)
+- Verify `KEYWARDEN_BASE_URL` is set correctly (needed for the invitation link)
+- Send a test email from Admin Settings to verify SMTP works
+
+## Backup Issues
+
+### "Failed to decrypt backup"
+
+**Cause**: Wrong backup password.
+
+**Solution**: Use the exact password that was provided during backup export.
+
+### "Failed to parse backup"
+
+**Cause**: The backup file is corrupt or not a valid `.kwbak` file.
+
+**Solution**: Ensure the file was not modified or corrupted during transfer.
+
+### SSH Keys Not Working After Restore
+
+**Cause**: The `KEYWARDEN_ENCRYPTION_KEY` in the current environment doesn't match the one used when the backup was created.
+
+**Solution**: Set `KEYWARDEN_ENCRYPTION_KEY` to the same value that was in use when the backup was created.
+
+## Performance
+
+### Slow Page Loads
+
+- Check the log level — `TRACE` and `DEBUG` can be verbose
+- SQLite WAL mode is enabled by default for better concurrent read performance
+- The in-memory session store scales well for typical deployments
+
+### High Memory Usage
+
+- Sessions are stored in memory — many active sessions increase memory
+- The session cleanup goroutine runs every minute to remove expired sessions
+- Avatar images are served from disk, not stored in memory
+
+## Logs
+
+### Viewing Logs
+
+```bash
+# Docker
+docker compose logs keywarden
+docker compose logs -f keywarden  # follow
+
+# Log levels
+KEYWARDEN_LOG_LEVEL=DEBUG  # more detail
+KEYWARDEN_LOG_LEVEL=TRACE  # maximum verbosity
+```
+
+### Log Levels
+
+| Level | Output |
+|---|---|
+| `ERROR` | Only errors |
+| `WARN` | Errors + warnings |
+| `INFO` | Errors + warnings + informational (default) |
+| `DEBUG` | All of the above + debug details |
+| `TRACE` | Maximum verbosity, including request/response details |
+
+### Request Logging
+
+Every HTTP request is logged with:
+- Method, path, status code
+- Response time
+- Client IP address
+- Username (if authenticated)