kvaps/letsencrypt-webroot

Let’s Encrypt (webroot) Docker镜像

!Letsencrypt Logo

本镜像基于letsencrypt基础镜像，提供SSL证书自动获取与续期脚本。

• https://github.com/kvaps/docker-letsencrypt-webroot
• https://hub.docker.com/r/kvaps/letsencrypt-webroot/

项目状态

本项目目前处于非维护状态。我会尽力处理PR，但无法保证及时响应，也没有精力解决问题或添加新功能。若您有兴趣接管该项目，请通过Issue告知。

使用方法

1. 配置Web服务器
   确保Web服务器能正确提供/.well-known/acme-challenge目录的内容。例如，Nginx需添加以下配置：

   nginx
   location '/.well-known/acme-challenge' {
       default_type "text/plain";
       root        /tmp/letsencrypt;
   }
   

2. 挂载卷
   运行Web服务器镜像时，需挂载以下卷：

   bash
   -v /data/letsencrypt:/etc/letsencrypt
   -v /data/letsencrypt-www:/tmp/letsencrypt
   

3. 启动镜像
   执行以下命令启动letsencrypt-webroot镜像：

   bash
   docker run \
     --name some-letsencrypt \
     -v /data/letsencrypt:/etc/letsencrypt \
     -v /data/letsencrypt-www:/tmp/letsencrypt \
     -e 'DOMAINS=example.com www.example.com' \
     -e 'EMAIL=your@email.tld' \
     -e 'WEBROOT_PATH=/tmp/letsencrypt' \
     kvaps/letsencrypt-webroot
   

4. 证书路径
   应用程序需使用以下证书路径：

   • 私钥: /etc/letsencrypt/live/example.com/privkey.pem
   • 证书: /etc/letsencrypt/live/example.com/cert.pem
   • 中间证书: /etc/letsencrypt/live/example.com/chain.pem
   • 完整证书链: /etc/letsencrypt/live/example.com/fullchain.pem

注意: 需完整挂载/etc/letsencrypt目录，仅挂载/etc/letsencrypt/live会导致证书 symlink 失效！

续期钩子

可设置钩子在证书续期后执行操作（如重启Web服务器）：

• 需挂载Docker sock：-v /var/run/docker.sock:/var/run/docker.sock
• 添加容器链接：--link some-nginx
• 设置环境变量LE_RENEW_HOOK：
  • Nginx重载：-e 'LE_RENEW_HOOK=docker kill -s HUP @CONTAINER_NAME@'
  • 容器重启：-e 'LE_RENEW_HOOK=docker restart @CONTAINER_NAME@'

Docker Compose示例

以下是Nginx与letsencrypt-webroot的组合配置： docker-compose.yml

yaml
nginx:
  restart: always
  image: nginx
  hostname: example.com
  volumes:
    - /etc/localtime:/etc/localtime:ro
    - ./nginx:/etc/nginx:ro
    - ./letsencrypt/conf:/etc/letsencrypt
    - ./letsencrypt/html:/tmp/letsencrypt
  ports:
    - 80:80
    - 443:443
  environment:
    - LE_RENEW_HOOK=docker kill -s HUP @CONTAINER_NAME@

letsencrypt:
  restart: always
  image: kvaps/letsencrypt-webroot
  volumes:
    - /etc/localtime:/etc/localtime:ro
    - /var/run/docker.sock:/var/run/docker.sock
    - ./letsencrypt/conf:/etc/letsencrypt
    - ./letsencrypt/html:/tmp/letsencrypt
  links:
    - nginx
  environment:
    - DOMAINS=example.com www.example.com
    - EMAIL=your@email.tld
    - WEBROOT_PATH=/tmp/letsencrypt
    - EXP_LIMIT=30
    - CHECK_FREQ=30
    - CHICKENEGG=
    - STAGING=

单次运行模式

添加once参数可让容器在证书更新后立即退出：

bash
docker run ... kvaps/letsencrypt-webroot once

环境变量

• DOMAINS: 证书覆盖的域名，如example.com www.example.com
• EMAIL: 用于紧急通知和密钥恢复的***
• WEBROOT_PATH: Web服务器中acme-challenge目录的路径，如/tmp/letsencrypt
• CHOWN: 证书文件的所有者，默认root:root
• CHMOD: 证书文件权限，默认644
• EXP_LIMIT: 证书到期前多少天触发续期，默认30天
• CHECK_FREQ: 检查证书状态的频率，默认30天
• CHICKENEGG: 设置为1时，在无证书时生成自签名证书（解决部分服务器启动问题）
• STAGING: 设置为1时使用Let's Encrypt测试环境（避免 rate limit）