8

In the case you have a website using Apache only (maybe with PHP) that is in:

/home/www/mywebsite/
/home/www/mywebsite/index.php
/home/www/mywebsite/style.css

then, it's easy to set certbot's --webroot-path:

./certbot-auto certonly --webroot --webroot-path /home/www/mywebsite/
                        --domain example.com --domain www.example.com --email a@example.com

Question: when using a website run by NodeJS or Python Flask or Bottle, linked to Apache either with WSGI (mod_wsgi) or simple proxying (I know the latter is not recommended in the case Python)

RewriteEngine On
RewriteRule /(.*)           http://localhost:5000/$1 [P,L]

what should --webroot-path be?

More specifically, if we have:

/home/www/mywebsite/       (Pyton example)
/home/www/mywebsite/myapp.py
/home/www/mywebsite/myapp.sqlite
/home/www/mywebsite/static/style.css
...

or

/home/www/mywebsite/        (NodeJS example)
/home/www/mywebsite/myapp.js
/home/www/mywebsite/myapp.sqlite
/home/www/mywebsite/static/style.css
...

then it doesn't make sense to choose --webroot-path as /home/www/mywebsite/, right?

Indeed, I don't want any other program/script like letsencrypt certbot to fiddle with my .py files.

Anyway, what does --webroot-path in certbot do? Will files there be analyzed, parsed?

Basj
  • 41,386
  • 99
  • 383
  • 673

2 Answers2

11

Very interesting question that yet has a trivial answer. The official documentation states:

The webroot plugin works by creating a temporary file for each of your requested domains in ${webroot-path}/.well-known/acme-challenge. Then the Let’s Encrypt validation server makes HTTP requests to validate that the DNS for each requested domain resolves to the server running certbot.

So it doesn't really matter for Certbot where your actual webroot really resides as long it's served under domain you're trying to obtain certificates for, and it's not really interested in what is your project/framework structure is.

In other words, certbot does not require access to your project's directory with source files.

For example, Apache configuration for any application on your server can have shared so-called webroot, and Certbot only requires /.well-known/acme-challenge/ available as static directory where it can store challenge file on the server side that will be available for Certbot validation server:

Alias /.well-known/acme-challenge/ "/var/www/html/.well-known/acme-challenge/"

<Directory "/var/www/html/">
    AllowOverride None
    Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
    Require method GET POST OPTIONS
</Directory>

Same way it works for NGINX when setting for a particular server block configuration:

server {

    location /.well-known/acme-challenge/ {
        alias /var/www/html/.well-known/acme-challenge/;
    }

}

Both examples would work if certificate is then requested with:

certbot-auto certonly --webroot --webroot-path /var/www/html -d domain.com
Damaged Organic
  • 8,175
  • 6
  • 58
  • 84
  • Thanks for your answer. I checked at the root of a PHP website for which I have used `certbot-auto` / Letsencrypt successfully a few days ago (e.g. `/home/www/mywebsite/`), but I don't find any `.well-known/acme-challenge` file there. I used `ls -la`, but I can't find them. How does this work? – Basj Apr 22 '18 at 19:03
  • 1
    It's really straightforward. When using the webroot method the Certbot client places a challenge response inside domain.com/.well-known/acme-challenge/ which is used for validation. When validation is complete, challenge file is removed from the target directory. – Damaged Organic Apr 22 '18 at 19:11
5

This is complementary information to DamagedOrganic's answer (full credit to him).

For certbot / Letsencrypt to validate a certificate, it has to be able to access a challenge/response URL like http://example.com/.well-known/acme-challenge/B39sdfoyoesdf21-qksl2638761867648514.
For this reason, it will create a temporary file (deleted at the end, that's why you won't find it anymore after a successful certbot) named .well-known/acme-challenge/B39sdfoyoesdf21-qksl2638761867648514 for example in the path given by --webroot-path. (Then Letsencrypt's servers will access the URL mentioned before in order to verify that everything is ok.).

Solution: Choose --webroot-path as the directory where static files are served. Example: if you have this structure:

/home/www/mywebsite/
/home/www/mywebsite/myapp.py
/home/www/mywebsite/myapp.sqlite
/home/www/mywebsite/static/style.css        # /static/ serves static files... 
/home/www/mywebsite/static/favicon.ico
...

then use

./certbot-auto certonly --webroot --webroot-path /home/www/mywebsite/static/
                        --domain example.com --domain www.example.com --email a@example.com

PS: this is a solution with Bottle (I think it would be similar with Flask):

@route('/.well-known/acme-challenge/<filename>')
def wellknown(filename):           # Letsencrypt certbot-auto
    return static_file(filename, root='./static/.well-known/acme-challenge')
Basj
  • 41,386
  • 99
  • 383
  • 673