forked from Nixius/authelia
93 lines
3.3 KiB
Markdown
93 lines
3.3 KiB
Markdown
# 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
|
|
|
|
4. **Full rebuild and redeploy (remove old stack/images)**
|
|
- Push to `main` (or run the production pipeline in Woodpecker). The pipeline: builds production images with `--no-cache`, pushes to registry, runs `scripts/ci-deploy-production.sh` (stack rm → wait → recreate secrets → deploy stack → health check → prune unused images).
|
|
- No manual steps on the swarm manager; everything runs in CI.
|
|
|
|
## 🔑 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.a250.ca
|
|
- **Development**: http://localhost:9091
|
|
- **Health Check**: https://login.a250.ca/api/health
|
|
- **OIDC Discovery**: https://login.a250.ca/.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.a250.ca/.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 |