SSL - rtCamp/Frappe-Manager GitHub Wiki

  • SSL generation with fm is done using Let's Encrypt client Certbot.
  • fm supported Letsencrypt challenges DNS01 and HTTP01.
  • For DNS01 challenge, fm only supports CloudFlare.

How to create a bench with ssl?

  • When setting up a bench, ensure to include the --ssl flag in the fm create command.
  • When only the --ssl flag is given, if DNS credentials are provided in fm_config.toml, the DNS challenge will be used by default and will fall back to HTTPS if the DNS challenge fails or if DNS credentials are not available

Using HTTP01 challenge

  • Remember to point the domain's DNS to the appropriate location.
fm create example.com --ssl letsencrypt --letsencrypt-preferred-challenge http01 --letsencrypt-email [email protected]

Using DNS01 challenge

Configure creds for DNS01 challenge

There are two ways to configure creds for this challenge. More info can be found here

  • Use global config fm_config.toml, if you want to set DNS creds which can be used by all benches.
  • Use bench_config.toml, if you want to use creds for only one bench.
fm create example.com --ssl letsencrypt --letsencrypt-preferred-challenge dns01 --letsencrypt-email [email protected]

How to update an existing bench with ssl?

To enable SSL in an existing bench, use the --ssl flag with the fm update command. This will utilize the Letsencrypt HTTP01 challenge to generate the SSL certificate. Additionally, remember to point the domain's DNS to the appropriate location.

Using fm update <bench> command

DNS01 challenge

  • Update bench_config.toml or fm_config.toml with the required DNS creds attributes using this guide.
fm update example.com --ssl letsencrypt --letsencrypt-preferred-challenge dns01 --letsencrypt-email [email protected]

HTTP01 challenge

  • Remember to point the domain's DNS to the appropriate location.
fm update example.com --ssl letsencrypt --letsencrypt-preferred-challenge http01 --letsencrypt-email [email protected]

Using configuration file.

Remember after changing the config files use please run command fm start <bench> to reflect the changes in bench.

DNS01 challenge

Using bench's bench_config.toml config file.

  • Update bench_config.toml with the required DNS creds attributes using this guide.

Using fm_config.toml with bench's bench_config.toml config file.

This configuration will utilize the fm_config.toml which is global configuration attributes to get api_key or api_token.

  • Update global config file fm_config.toml with the required DNS creds attributes using this guide.

  • Update bench config file bench_config.toml with the following

[ssl]
# Sets the SSL type to be used by the bench, in this case, "letsencrypt" for Let's Encrypt. 
ssl_type = "letsencrypt"

# Controls the HSTS (HTTP Strict Transport Security) header used by the bench. 
# When set to "off", the HSTS header will not be included. 
hsts = "off" 

# Specifies the preferred Certbot challenge method to be used for Let's Encrypt certificate validation. 
preferred_challenge = "dns01"

HTTP01 challenge

  • Remember to point the domain's DNS to the appropriate location.
  • Update bench_config.toml with the following
[ssl]
# Sets the SSL type to be used by the bench, in this case, "letsencrypt" for Let's Encrypt. 
ssl_type = "letsencrypt"

# Controls the HSTS (HTTP Strict Transport Security) header used by the bench. 
# When set to "off", the HSTS header will not be included. 
hsts = "off" 

# This is used for notifications, recovery.
email = "[email protected]" 

# Specifies the preferred Certbot challenge method to be used for Let's Encrypt certificate validation. 
preferred_challenge = "http01"

How to remove ssl from existing bench with ssl?

To remove SSL from an existing bench, use the –ssl flag with the fm update command

fm update example.com --ssl disable

or alternatively you can use the fm ssl delete command

fm ssl delete example.com

How to add automatic SSL renewal?

  • For automatic SSL certificate renewal, add the following cron job. This cron will execute at midnight on the first day of each month.
  • Configure this in host machine not in the containers.

For specific bench

0 0 1 * * fm ssl renew example.com >> ~/frappe/logs/renew.logs

For all benches

0 0 1 * * fm ssl renew --all >> ~/frappe/logs/renew.logs

Configure Cloudflare DNS Credentials

  • Cloudflare credentials can be configured using two type of authentication. Please read this to understand api_key ( CloudFlare Global API Key ) and api_token ( CloudFlare API Token ) utilization and creation process requirements.

Global Credentials

  • Can be utilized by all the benches.
  • Add these attributes to fm_config.toml file.

Using Cloudflare Global API Key

...

[letsencrypt]
# email which is used with api_key for the Global API key of Cloudflare.
email = '[email protected]'

# Cloudflare Global API Key for Let's Encrypt DNS01 Challenge. 
api_key = '0123456789abcdef0123456789abcdef01234'

Using Cloudflare API Token

...

[letsencrypt]
# This is used for notifications, recovery.
email = '[email protected]'
# Cloudflare API token for Let's Encrypt DNS01 Challenge.
api_token = '0123456789abcdef0123456789abcdef01234567'

Bench specific credentials

Add these attributes to the specific bench's bench_config.toml file.

Using Cloudflare Global API Key

...

[ssl]
# Sets the SSL type to be used by the bench, in this case, "letsencrypt" for Let's Encrypt. 
ssl_type = "letsencrypt"

# Controls the HSTS (HTTP Strict Transport Security) header used by the bench. 
# When set to "off", the HSTS header will not be included. 
hsts = "off" 

# Specifies the preferred Certbot challenge method to be used for Let's Encrypt certificate validation. 
preferred_challenge = "dns01"

# email which is used with api_key for the Global API key of Cloudflare.
email = '[email protected]'

# Cloudflare Global API Key for Let's Encrypt DNS01 Challenge. 
api_key = "0123456789abcdef0123456789abcdef01234"

Using Cloudflare API Token

...

[ssl]
# Sets the SSL type to be used by the bench, in this case, "letsencrypt" for Let's Encrypt. 
ssl_type = "letsencrypt"

# Controls the HSTS (HTTP Strict Transport Security) header used by the bench. 
# When set to "off", the HSTS header will not be included. 
hsts = "off" 

# Specifies the preferred Certbot challenge method to be used for Let's Encrypt certificate validation. 
preferred_challenge = "dns01"

# This is used for notifications, recovery.
email = '[email protected]'

# Cloudflare API token for Let's Encrypt DNS01 Challenge.
api_token = '0123456789abcdef0123456789abcdef01234567'
⚠️ **GitHub.com Fallback** ⚠️