# Documentation Index

This directory contains comprehensive guides for Authelia deployment and configuration.

## 📚 Available Guides

### 🔧 Setup & Configuration
- **[OAuth/OIDC Setup Guide](OAUTH_SETUP.md)** - Complete OAuth integration for Portainer, Gitea, and other services
- **[CI/CD Vault Setup](CI_CD_VAULT_SETUP.md)** - Secret management and Woodpecker CI vault configuration

### 🚀 Getting Started

1. **Initial Deployment**
   - Follow the main [README.md](../README.md) for basic setup
   - Generate core secrets with `./generate-secrets.sh`
   - Set up CI/CD vault using [CI/CD Vault Setup](CI_CD_VAULT_SETUP.md)

2. **OAuth Integration** 
   - Generate OAuth client secrets with `./scripts/generate-oauth-secrets.sh`
   - Follow [OAuth Setup Guide](OAUTH_SETUP.md) for service configuration
   - Configure individual services (Portainer, Gitea) with OAuth

3. **Production Deployment**
   - Commit changes to trigger CI/CD pipeline
   - Monitor deployment through Woodpecker CI
   - Verify service health and authentication flows

## 🔑 Quick Reference

### Essential Commands
```bash
# Generate core Authelia secrets (10 secrets)
./generate-secrets.sh

# Generate OAuth client secrets (2 additional secrets)  
./scripts/generate-oauth-secrets.sh

# Run development environment
docker compose -f docker-compose.dev.yml up -d

# Run tests
./tests/precommit.sh
```

### Important URLs
- **Authelia**: https://login.nixc.us
- **Development**: http://localhost:9091
- **Health Check**: https://login.nixc.us/api/health
- **OIDC Discovery**: https://login.nixc.us/.well-known/openid_configuration

### Required Secrets (12 Total)
- **Core Secrets (5)**: LDAP, JWT, encryption, session, SMTP
- **OIDC Secrets (3)**: HMAC, private key, JWKS key  
- **Client Secrets (4)**: Headscale (2), Portainer, Gitea

## 🔍 Troubleshooting

### Common Issues
- **Service won't start**: Check secrets in CI vault
- **OAuth fails**: Verify redirect URIs and client secrets
- **Database errors**: Check MariaDB connectivity and initialization
- **Health check fails**: Verify Authelia startup and port binding

### Useful Commands
```bash
# Check service logs
ssh macmini7 'docker service logs authelia_authelia --follow'

# Verify secrets access
ssh macmini7 'docker service logs authelia_authelia | grep -i secret'

# Test OAuth endpoints
curl -s https://login.nixc.us/.well-known/openid_configuration | jq .
```

## 📞 Support

For issues not covered in these guides:
1. Check service logs for specific error messages
2. Verify all secrets are present in CI vault
3. Confirm network connectivity between services
4. Review Authelia configuration for syntax errors

## 🔄 Updates

Keep documentation synchronized with code changes:
- Update OAuth client configurations when adding new services
- Refresh secret generation procedures when security requirements change
- Document new troubleshooting steps as issues are resolved