update readme

2025-05-23 21:50:12 +05:00
parent 7ee1afbd7b
commit 6c07302caf
1 changed files with 139 additions and 14 deletions
--- a/README.md
+++ b/README.md
@@ -1,15 +1,45 @@
-## Generate Free SSL Certificates
+# Generate Free SSL Certificates

-This docker container generates free SSL certificates using Letsencrypt using Cloudlfare DNS Plugin
+This Docker container generates free SSL certificates using Let's Encrypt with the Cloudflare DNS plugin. \
+It supports wildcard certificates and multiple domains per certificate.

+## Prerequisites
+
+- Docker and Docker Compose installed
+- Domains managed through Cloudflare DNS
+- Cloudflare Global API Key or API Token with Zone:Read and DNS:Edit permissions
+
+## How to Use
+
+### 1. Set up environment file
+
+Copy `.env.example` to `.env` and fill in your details:
+
+```bash
+cp .env.example .env
+```
+
+**Environment Variables:**
+- `CLOUDFLARE_EMAIL=` - Your Cloudflare account email address
+- `CLOUDFLARE_API_KEY=` - Get from [Cloudflare Dashboard > Profile > API Tokens](https://dash.cloudflare.com/profile/api-tokens)
+  - Use either Global API Key or create a custom token with `Zone:Read` and `DNS:Edit` permissions
+- `CERTBOT_EMAIL=` - Email for Let's Encrypt notifications (certificate expiry warnings)
+- `DOMAINS=` - Comma-separated list of domains for the certificate
+  - Supports wildcards: `*.example.com,example.com`
+  - Multiple domains: `example.com,api.example.com,*.sub.example.com`
+
+**Example .env file:**
+```env
+CLOUDFLARE_EMAIL=user@example.com
+CLOUDFLARE_API_KEY=your_global_api_key_here
+CERTBOT_EMAIL=admin@example.com
+DOMAINS=example.com,*.example.com,api.example.com
+```
+
+### 2. Create Docker Compose file
+
+Save the following as `compose.yml`:

-# How to use
-1. Copy ` .env.example` to `.env` and fill it. \
-  `CLOUDFLARE_EMAIL=` is your cloudflare account email \
-  `CLOUDFLARE_API_KEY=` you can get it from [https://dash.cloudflare.com/profile/api-tokens](Cloudflare profile > API Tokens) \
-  `CERTBOT_EMAIL=` this email is for letsencrypt to send you cert expiry notification \
-  `DOMAINS=` write domains you want ssl for seperated by commas, wildcard is supported (*.example.com) \
-2. Save following content as `compose.yml`
 ```yml
 services:
  certgen:
@@ -19,15 +49,110 @@ services:
      - ./certs:/etc/letsencrypt/archive
    env_file: .env
    restart: no
-#  certgen-sar:
+#  certgen2:
 #    image: git.shihaam.dev/shihaam/gen-ssl-letsencrypt-cf
-#    hostname: certgen-sar
+#    hostname: certgen2
 #    volumes:
 #      - ./certs:/etc/letsencrypt/archive
-#    env_file: .env_sar
+#    env_file: .env_account2
 #    restart: no
+
 ```
-3. Run `docker compose up` and wait
-4. Your cert and key will be saved in `certs` folder
+- You can uncomment 2nd service to genereate certs for domain in another account.

+### 3. Generate certificates

+Run the container:
+```bash
+docker compose up
+```
+
+The container will:
+- Validate your Cloudflare credentials
+- Create DNS TXT records for domain validation
+- Generate and download certificates
+- Clean up DNS records
+- Exit automatically when complete
+
+### 4. Access your certificates
+
+Certificates are saved in the `certs/` directory:
+
+```
+certs/
+├── omegatechsolution.org
+│   ├── cert1.pem
+│   ├── chain1.pem
+│   ├── fullchain1.pem
+│   └── privkey1.pem
+└── sar.sh
+    ├── cert1.pem
+    ├── chain1.pem
+    ├── fullchain1.pem
+    └── privkey1.pem
+```
+Note: The folder name is the first domain in the array, Certs will be valid for all domains.
+
+**For web servers:**
+- **Nginx**: Use `fullchain.pem` + `privkey.pem`
+- **Apache**: Use `cert.pem` + `chain.pem` + `privkey.pem`
+
+## Multiple Accounts/Certificate Sets
+
+To generate certificates for multiple Cloudflare accounts or different domain sets:
+
+1. Create additional environment files:
+```bash
+cp .env .env_account2
+# Edit .env_account2 with different credentials/domains
+```
+
+2. Uncomment and modify the second service in `compose.yml`
+
+3. Run specific services:
+```bash
+# Generate for primary account
+docker compose up certgen
+
+# Generate for secondary account
+docker compose up certgen2
+
+# Generate for all accounts
+docker compose up
+```
+
+## Certificate Renewal
+
+Certificates are valid for 90 days. To renew:
+
+1. Run the same `docker compose up` command
+2. Let's Encrypt will automatically renew certificates expiring within 30 days
+
+## Troubleshooting
+
+**Common Issues:**
+
+- **"Invalid credentials"**: Verify your Cloudflare email and API key
+- **"Domain not found"**: Ensure domains are managed by your Cloudflare account
+- **"Rate limited"**: Let's Encrypt has rate limits (50 certificates per week per domain)
+- **"DNS propagation failed"**: Wait a few minutes and retry
+
+**Debug mode:**
+```bash
+# Add to your .env file for verbose output
+CERTBOT_ARGS=--verbose
+```
+## Security Notes
+
+- Keep your `.env` file secure and never commit it to version control
+- Use API tokens instead of Global API Key when possible
+- Restrict API token permissions to only necessary zones
+- Regularly rotate your API credentials
+
+## Supported Features
+
+- ✅ Wildcard certificates (`*.example.com`)
+- ✅ Multiple domains per certificate
+- ✅ Multiple Cloudflare accounts
+- ✅ Automatic DNS validation
+- ✅ Certificate renewal