4cc61a955d
- Add a comprehensive .gitignore to manage project files. - Create the basic project structure including Cargo.toml, LICENSE, and README.md. - Add basic project documentation.
121 lines
3.9 KiB
Markdown
121 lines
3.9 KiB
Markdown
# Troubleshooting Guide
|
|
|
|
This guide provides solutions to common issues you might encounter when using the Hostbasket application.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Authentication Issues](#authentication-issues)
|
|
- [Missing CSRF Token](#missing-csrf-token)
|
|
- [Invalid CSRF Token](#invalid-csrf-token)
|
|
- [JWT Token Issues](#jwt-token-issues)
|
|
2. [OAuth Issues](#oauth-issues)
|
|
- [Gitea Authentication Errors](#gitea-authentication-errors)
|
|
3. [Server Issues](#server-issues)
|
|
- [Port Already in Use](#port-already-in-use)
|
|
- [Template Parsing Errors](#template-parsing-errors)
|
|
|
|
## Authentication Issues
|
|
|
|
### Missing CSRF Token
|
|
|
|
**Problem**: When trying to authenticate with Gitea, you receive a "Missing CSRF token" error.
|
|
|
|
**Solutions**:
|
|
|
|
1. **Check your SECRET_KEY environment variable**:
|
|
- Ensure you have a valid SECRET_KEY in your `.env` file
|
|
- The SECRET_KEY must be at least 32 bytes long
|
|
- Example: `SECRET_KEY=01234567890123456789012345678901`
|
|
|
|
2. **Enable debug logging**:
|
|
- Set `RUST_LOG=debug` in your `.env` file
|
|
- Restart the application
|
|
- Check the logs for more detailed information
|
|
|
|
3. **Clear browser cookies**:
|
|
- Clear all cookies for your application domain
|
|
- Try the authentication process again
|
|
|
|
4. **Check session configuration**:
|
|
- Make sure your session middleware is properly configured
|
|
- The SameSite policy should be set to "Lax" for OAuth redirects
|
|
|
|
### Invalid CSRF Token
|
|
|
|
**Problem**: When trying to authenticate with Gitea, you receive an "Invalid CSRF token" error.
|
|
|
|
**Solutions**:
|
|
|
|
1. **Check for multiple tabs/windows**:
|
|
- Make sure you're not trying to authenticate in multiple tabs/windows simultaneously
|
|
- Each authentication attempt generates a new CSRF token
|
|
|
|
2. **Check for browser extensions**:
|
|
- Some browser extensions might interfere with cookies or redirects
|
|
- Try disabling extensions or using a different browser
|
|
|
|
### JWT Token Issues
|
|
|
|
**Problem**: You're logged in but keep getting redirected to the login page.
|
|
|
|
**Solutions**:
|
|
|
|
1. **Check JWT_SECRET**:
|
|
- Ensure your JWT_SECRET is consistent across application restarts
|
|
- Set a permanent JWT_SECRET in your `.env` file
|
|
|
|
2. **Check token expiration**:
|
|
- The default token expiration is 24 hours
|
|
- You can adjust this with the JWT_EXPIRATION_HOURS environment variable
|
|
|
|
## OAuth Issues
|
|
|
|
### Gitea Authentication Errors
|
|
|
|
**Problem**: You encounter errors when trying to authenticate with Gitea.
|
|
|
|
**Solutions**:
|
|
|
|
1. **Check OAuth configuration**:
|
|
- Verify your GITEA_CLIENT_ID and GITEA_CLIENT_SECRET are correct
|
|
- Make sure your GITEA_INSTANCE_URL is correct and accessible
|
|
- Ensure your APP_URL is set correctly for the callback URL
|
|
|
|
2. **Check Gitea application settings**:
|
|
- Verify the redirect URI in your Gitea application settings matches your callback URL
|
|
- The redirect URI should be: `http://localhost:9999/auth/gitea/callback` (adjust as needed)
|
|
|
|
3. **Check network connectivity**:
|
|
- Ensure your application can reach the Gitea instance
|
|
- Check for any firewalls or network restrictions
|
|
|
|
## Server Issues
|
|
|
|
### Port Already in Use
|
|
|
|
**Problem**: When starting the application, you get an "Address already in use" error.
|
|
|
|
**Solutions**:
|
|
|
|
1. **Change the port**:
|
|
- Set a different port in your `.env` file: `APP__SERVER__PORT=8080`
|
|
- Or use the command-line flag: `cargo run -- --port 8080`
|
|
|
|
2. **Find and stop the process using the port**:
|
|
- On Linux/macOS: `lsof -i :9999` to find the process
|
|
- Then `kill <PID>` to stop it
|
|
|
|
### Template Parsing Errors
|
|
|
|
**Problem**: The application fails to start with template parsing errors.
|
|
|
|
**Solutions**:
|
|
|
|
1. **Check template syntax**:
|
|
- Verify that all your Tera templates have valid syntax
|
|
- Look for unclosed tags, missing blocks, or invalid expressions
|
|
|
|
2. **Check template directory**:
|
|
- Make sure your APP__TEMPLATES__DIR environment variable is set correctly
|
|
- The default is `./src/views`
|