gitea-mirror/certs

Custom CA Certificate Support

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.

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.

Configuration Steps

1. Prepare Your CA Certificates

You're already in the right place! Simply copy your CA certificate(s) into this certs directory with .crt extension:

# From the project root:
cp /path/to/your/ca-certificate.crt ./certs/

# Or if you're already in the certs directory:
cp /path/to/your/ca-certificate.crt .

You can add multiple CA certificates - they will all be combined into a single bundle.

2. Mount Certificates in Docker

Edit your docker-compose.yml file to mount the certificates. You have two options:

Option 1: Mount individual certificates from certs directory

services:
  gitea-mirror:
    # ... other configuration ...
    volumes:
      - gitea-mirror-data:/app/data
      - ./certs:/app/certs:ro  # Mount CA certificates directory

Option 2: Mount system CA bundle (if your CA is already installed system-wide)

services:
  gitea-mirror:
    # ... other configuration ...
    volumes:
      - gitea-mirror-data:/app/data
      - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro

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.

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

3. Start the Container

Start or restart your container:

docker-compose up -d

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

You should see log messages like:

For Option 1 (individual certificates):

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

For Option 2 (system CA bundle):

System CA bundle mounted, configuring Node.js to use it...
NODE_EXTRA_CA_CERTS set to: /etc/ssl/certs/ca-certificates.crt

Testing & Troubleshooting

Disable TLS Verification (Testing Only)

For testing purposes only, you can disable TLS verification entirely:

environment:
  - GITEA_SKIP_TLS_VERIFY=true

WARNING: This is insecure and should never be used in production!

Common Issues

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

Verifying Certificate Loading

Check the container logs to confirm certificates are loaded:

docker-compose logs gitea-mirror | grep "CA certificates"

Security Considerations

• 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

Example Setup

Here's a complete example for a self-hosted Gitea with custom CA:

1. Copy your Gitea server's CA certificate to this directory:

   cp /etc/ssl/certs/my-company-ca.crt ./certs/
   

2. Update docker-compose.yml:

   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 ...
   

3. Start the service:

   docker-compose up -d
   

The application will now trust your custom CA when connecting to your Gitea instance.