authelia/docs/README.md

Documentation Index

This directory contains comprehensive guides for Authelia deployment and configuration.

📚 Available Guides

🔧 Setup & Configuration

• OAuth/OIDC Setup Guide - Complete OAuth integration for Portainer, Gitea, and other services
• CI/CD Vault Setup - Secret management and Woodpecker CI vault configuration

🚀 Getting Started

1. Initial Deployment

   • Follow the main README.md for basic setup
   • Generate core secrets with ./generate-secrets.sh
   • Set up CI/CD vault using CI/CD Vault Setup

2. OAuth Integration

   • Generate OAuth client secrets with ./scripts/generate-oauth-secrets.sh
   • Follow OAuth Setup Guide 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

# 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

# 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