Added SSO and OIDC

Author: arunavo4

certs/README.md

@@ -1,149 +1,236 @@
-# Custom CA Certificate Support
+# CA Certificates Configuration
 
-This guide explains how to configure Gitea Mirror to work with self-signed certificates or custom Certificate Authorities (CAs).
-
-> **📁 This is the certs directory!** Place your `.crt` certificate files directly in this directory and they will be automatically loaded when the Docker container starts.
+This document explains how to configure custom Certificate Authority (CA) certificates for Gitea Mirror when connecting to self-signed or privately signed Gitea instances.
 
 ## Overview
 
-When connecting to a Gitea instance that uses self-signed certificates or certificates from a private CA, you need to configure the application to trust these certificates. Gitea Mirror supports mounting custom CA certificates that will be automatically configured for use.
+When your Gitea instance uses a self-signed certificate or a certificate signed by a private Certificate Authority (CA), you need to configure Gitea Mirror to trust these certificates.
 
-## Configuration Steps
+## Common SSL/TLS Errors
 
-### 1. Prepare Your CA Certificates
+If you encounter any of these errors, you need to configure CA certificates:
 
-You're already in the right place! Simply copy your CA certificate(s) into this `certs` directory with `.crt` extension:
+- `UNABLE_TO_VERIFY_LEAF_SIGNATURE`
+- `SELF_SIGNED_CERT_IN_CHAIN`
+- `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`
+- `CERT_UNTRUSTED`
+- `unable to verify the first certificate`
 
-```bash
-# From the project root:
-cp /path/to/your/ca-certificate.crt ./certs/
+## Configuration by Deployment Method
 
-# Or if you're already in the certs directory:
-cp /path/to/your/ca-certificate.crt .
-```
+### Docker
 
-You can add multiple CA certificates - they will all be combined into a single bundle.
+#### Method 1: Volume Mount (Recommended)
 
-### 2. Mount Certificates in Docker
+1. Create a certificates directory:
+   ```bash
+   mkdir -p ./certs
+   ```
 
-Edit your `docker-compose.yml` file to mount the certificates. You have two options:
+2. Copy your CA certificate(s):
+   ```bash
+   cp /path/to/your-ca-cert.crt ./certs/
+   ```
 
-**Option 1: Mount individual certificates from certs directory**
-```yaml
-services:
-  gitea-mirror:
-    # ... other configuration ...
-    volumes:
-      - gitea-mirror-data:/app/data
-      - ./certs:/app/certs:ro  # Mount CA certificates directory
-```
+3. Update `docker-compose.yml`:
+   ```yaml
+   version: '3.8'
+   services:
+     gitea-mirror:
+       image: raylabs/gitea-mirror:latest
+       volumes:
+         - ./data:/app/data
+         - ./certs:/usr/local/share/ca-certificates:ro
+       environment:
+         - NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/your-ca-cert.crt
+   ```
 
-**Option 2: Mount system CA bundle (if your CA is already installed system-wide)**
-```yaml
-services:
-  gitea-mirror:
-    # ... other configuration ...
-    volumes:
-      - gitea-mirror-data:/app/data
-      - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro
-```
+4. Restart the container:
+   ```bash
+   docker-compose down && docker-compose up -d
+   ```
 
-> **Note**: Use Option 2 if you've already added your CA certificate to your system's certificate store using `update-ca-certificates` or similar commands.
+#### Method 2: Custom Docker Image
 
-> **System CA Bundle Locations**:
-> - Debian/Ubuntu: `/etc/ssl/certs/ca-certificates.crt`
-> - RHEL/CentOS/Fedora: `/etc/pki/tls/certs/ca-bundle.crt`
-> - Alpine Linux: `/etc/ssl/certs/ca-certificates.crt`
-> - macOS: `/etc/ssl/cert.pem`
+Create a `Dockerfile`:
 
-### 3. Start the Container
+```dockerfile
+FROM raylabs/gitea-mirror:latest
 
-Start or restart your container:
+# Copy CA certificates
+COPY ./certs/*.crt /usr/local/share/ca-certificates/
 
+# Update CA certificates
+RUN update-ca-certificates
+
+# Set environment variable
+ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/your-ca-cert.crt
+```
+
+Build and use:
 ```bash
-docker-compose up -d
+docker build -t my-gitea-mirror .
 ```
 
-The container will automatically:
-1. Detect any `.crt` files in `/app/certs` (Option 1) OR detect mounted system CA bundle (Option 2)
-2. For Option 1: Combine certificates into a CA bundle
-3. Configure Node.js to use these certificates via `NODE_EXTRA_CA_CERTS`
+### Native/Bun
+
+#### Method 1: Environment Variable
+
+```bash
+export NODE_EXTRA_CA_CERTS=/path/to/your-ca-cert.crt
+bun run start
+```
 
-You should see log messages like:
+#### Method 2: .env File
 
-**For Option 1 (individual certificates):**
+Add to your `.env` file:
 ```
-Custom CA certificates found, configuring Node.js to use them...
-Adding certificate: my-ca.crt
-NODE_EXTRA_CA_CERTS set to: /app/certs/ca-bundle.crt
+NODE_EXTRA_CA_CERTS=/path/to/your-ca-cert.crt
+```
+
+#### Method 3: System CA Store
+
+**Ubuntu/Debian:**
+```bash
+sudo cp your-ca-cert.crt /usr/local/share/ca-certificates/
+sudo update-ca-certificates
 ```
 
-**For Option 2 (system CA bundle):**
+**RHEL/CentOS/Fedora:**
+```bash
+sudo cp your-ca-cert.crt /etc/pki/ca-trust/source/anchors/
+sudo update-ca-trust
 ```
-System CA bundle mounted, configuring Node.js to use it...
-NODE_EXTRA_CA_CERTS set to: /etc/ssl/certs/ca-certificates.crt
+
+**macOS:**
+```bash
+sudo security add-trusted-cert -d -r trustRoot \
+  -k /Library/Keychains/System.keychain your-ca-cert.crt
 ```
 
-## Testing & Troubleshooting
+### LXC Container (Proxmox VE)
+
+1. Enter the container:
+   ```bash
+   pct enter <container-id>
+   ```
+
+2. Create certificates directory:
+   ```bash
+   mkdir -p /usr/local/share/ca-certificates
+   ```
+
+3. Copy your CA certificate:
+   ```bash
+   cat > /usr/local/share/ca-certificates/your-ca.crt
+   ```
+   (Paste certificate content and press Ctrl+D)
+
+4. Update the systemd service:
+   ```bash
+   cat >> /etc/systemd/system/gitea-mirror.service << EOF
+   Environment="NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/your-ca.crt"
+   EOF
+   ```
+
+5. Reload and restart:
+   ```bash
+   systemctl daemon-reload
+   systemctl restart gitea-mirror
+   ```
 
-### Disable TLS Verification (Testing Only)
+## Multiple CA Certificates
 
-For testing purposes only, you can disable TLS verification entirely:
+### Option 1: Bundle Certificates
 
-```yaml
-environment:
-  - GITEA_SKIP_TLS_VERIFY=true
+```bash
+cat ca-cert1.crt ca-cert2.crt ca-cert3.crt > ca-bundle.crt
+export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt
 ```
 
-**WARNING**: This is insecure and should never be used in production!
+### Option 2: System CA Store
 
-### Common Issues
+```bash
+# Copy all certificates
+cp *.crt /usr/local/share/ca-certificates/
+update-ca-certificates
+```
 
-1. **Certificate not recognized**: Ensure your certificate file has a `.crt` extension
-2. **Connection still fails**: Check that the certificate is in PEM format
-3. **Multiple certificates needed**: Add all required certificates (root and intermediate) to the certs directory
+## Verification
 
-### Verifying Certificate Loading
+### 1. Test Gitea Connection
+Use the "Test Connection" button in the Gitea configuration section.
 
-Check the container logs to confirm certificates are loaded:
+### 2. Check Logs
 
+**Docker:**
 ```bash
-docker-compose logs gitea-mirror | grep "CA certificates"
+docker logs gitea-mirror
 ```
 
-## Security Considerations
+**Native:**
+Check terminal output
 
-- Always use proper CA certificates in production
-- Never disable TLS verification in production environments
-- Keep your CA certificates secure and limit access to the certs directory
-- Regularly update certificates before they expire
+**LXC:**
+```bash
+journalctl -u gitea-mirror -f
+```
 
-## Example Setup
+### 3. Manual Certificate Test
 
-Here's a complete example for a self-hosted Gitea with custom CA:
+```bash
+openssl s_client -connect your-gitea-domain.com:443 -CAfile /path/to/ca-cert.crt
+```
 
-1. Copy your Gitea server's CA certificate to this directory:
-   ```bash
-   cp /etc/ssl/certs/my-company-ca.crt ./certs/
-   ```
+## Best Practices
 
-2. Update `docker-compose.yml`:
-   ```yaml
-   services:
-     gitea-mirror:
-       image: ghcr.io/raylabshq/gitea-mirror:latest
-       volumes:
-         - gitea-mirror-data:/app/data
-         - ./certs:/app/certs:ro
-       environment:
-         - GITEA_URL=https://gitea.mycompany.local
-         - GITEA_TOKEN=your-token
-         # ... other configuration ...
-   ```
+1. **Certificate Security**
+   - Keep CA certificates secure
+   - Use read-only mounts in Docker
+   - Limit certificate file permissions
+   - Regularly update certificates
 
-3. Start the service:
-   ```bash
-   docker-compose up -d
-   ```
+2. **Certificate Management**
+   - Use descriptive certificate filenames
+   - Document certificate purposes
+   - Track certificate expiration dates
+   - Maintain certificate backups
+
+3. **Production Deployment**
+   - Use proper SSL certificates when possible
+   - Consider Let's Encrypt for public instances
+   - Implement certificate rotation procedures
+   - Monitor certificate expiration
+
+## Troubleshooting
 
-The application will now trust your custom CA when connecting to your Gitea instance.
+### Certificate not being recognized
+- Ensure the certificate is in PEM format
+- Check that `NODE_EXTRA_CA_CERTS` points to the correct file
+- Restart the application after adding certificates
+
+### Still getting SSL errors
+- Verify the complete certificate chain is included
+- Check if intermediate certificates are needed
+- Ensure the certificate matches the server hostname
+
+### Certificate expired
+- Check validity: `openssl x509 -in cert.crt -noout -dates`
+- Update with new certificate from your CA
+- Restart Gitea Mirror after updating
+
+## Certificate Format
+
+Certificates must be in PEM format. Example:
+
+```
+-----BEGIN CERTIFICATE-----
+MIIDXTCCAkWgAwIBAgIJAKl8bUgMdErlMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
+[... certificate content ...]
+-----END CERTIFICATE-----
+```
+
+If your certificate is in DER format, convert it:
+```bash
+openssl x509 -inform der -in certificate.cer -out certificate.crt
+```