Rewrite README with new config file documentation

This commit is contained in:
Brian Picciano 2023-07-09 17:13:25 +02:00
parent ceb2ba3cf4
commit 7d64f44dab
2 changed files with 72 additions and 52 deletions

120
README.md
View File

@ -21,63 +21,83 @@ A statically compiled binary will be placed in the `result` directory.
## Configuration
Domani is configured via command-line arguments or environment variables:
Domani is configured via a YAML file whose path is given on the command-line.
The format of the YAML file, along with all default values, is as follows:
```yaml
origin:
# Path under which all origin data (i.e. git repositories, file caches,
# etc...) will be stored.
#
# This should be different than any other store_dir_paths.
store_dir_path: REQUIRED
domain:
# Path under which all domain data (i.e. domains configured by users, HTTPS
# certificates, etc...) will be stored.
#
# This should be different than any other store_dir_paths.
store_dir_path: REQUIRED
#dns:
# Address of DNS resolver to use.
#resolver_addr: "1.1.1.1:53"
#acme:
# Contact email to use when creating HTTPS certificates using LetsEncrypt.
# This email will be used for notifying you if certificates are not being
# renewed.
#contact_email: REQUIRED if service.http.https_addr is set
service:
# Passphrase which must be given by users who are configuring new domains via
# the web interface.
passphrase: foobar
# DNS records which users must add to their domain's DNS so that
# Domani can serve the domains. All records given must route to this Domani
# instance. At least one record must be given.
dns_records:
#- type: A
# addr: 127.0.0.1
# The domain name which will be used to serve the web interface of Domani. If
# service.http.https_addr is enabled then an HTTPS certificate for this domain
# will be retrieved automatically.
# primary_domain: "localhost"
#http:
# The address to listen for HTTP requests on. This must use port 80 if
# https_addr is set.
#http_addr: "[::]:3030"
# The address to listen for HTTPS requests on. This is optional.
#https_addr: "[::]:443"
```
The YAML config file can be passed to the Domani process via the `--config-path`
CLI parameter:
```
--http-domain <HTTP_DOMAIN>
[env: DOMANI_HTTP_DOMAIN=]
--http-listen-addr <HTTP_LISTEN_ADDR>
[env: DOMANI_HTTP_LISTEN_ADDR=] [default: [::]:3030]
--https-listen-addr <HTTPS_LISTEN_ADDR>
E.g. '[::]:443', if given then SSL certs will automatically be retrieved for all domains using LetsEncrypt [env: DOMANI_HTTPS_LISTEN_ADDR=]
--passphrase <PASSPHRASE>
[env: DOMANI_PASSPHRASE=]
--origin-store-git-dir-path <ORIGIN_STORE_GIT_DIR_PATH>
[env: DOMANI_ORIGIN_STORE_GIT_DIR_PATH=]
--domain-checker-target-a <DOMAIN_CHECKER_TARGET_A>
[env: DOMANI_DOMAIN_CHECKER_TARGET_A=]
--domain-checker-resolver-addr <DOMAIN_CHECKER_RESOLVER_ADDR>
[env: DOMANI_DOMAIN_CHECKER_RESOLVER_ADDR=] [default: 1.1.1.1:53]
--domain-config-store-dir-path <DOMAIN_CONFIG_STORE_DIR_PATH>
[env: DOMANI_DOMAIN_CONFIG_STORE_DIR_PATH=]
--domain-acme-store-dir-path <DOMAIN_ACME_STORE_DIR_PATH>
[env: DOMANI_DOMAIN_ACME_STORE_DIR_PATH=]
--domain-acme-contact-email <DOMAIN_ACME_CONTACT_EMAIL>
[env: DOMANI_DOMAIN_ACME_CONTACT_EMAIL=]
-h, --help
Print help
-V, --version
Print version
domani --config-path <path>
```
### HTTPS Support
Domani will automatically handle setting up HTTPS via LetsEncrypt for both the
domani frontend site and all domains which it has been configured to serve.
By default HTTPS is not enabled, but can be enabled by setting the
`service.http.https_addr` field in the YAML config. There are a few other fields
in the configuration file which must be correctly configured if HTTPS is set up,
please read through the example file above carefully.
By default HTTPS is not enabled, but can be easily enabled by setting the
following arguments:
```
--https-listen-addr='[::]:443'
--domain-acme-contact-email='foo@example.com'
--domain-acme-store-dir-path='/some/secure/directory'
```
The contact email can be anything, it doesn't have to be real. The store
directory will have all SSL private keys written to it, and so should be
secured as best as possible.
Once HTTPS is enabled, Domani will automatically handle setting it up via
LetsEncrypt for both the Domani web interface and all domains which it is
configured to serve.
## Development

View File

@ -25,10 +25,10 @@ impl From<ConfigDNSRecord> for domain::checker::DNSRecord {
#[derive(Deserialize)]
pub struct Config {
#[serde(default = "default_primary_domain")]
pub primary_domain: domain::Name,
pub passphrase: String,
pub dns_records: Vec<ConfigDNSRecord>,
#[serde(default = "default_primary_domain")]
pub primary_domain: domain::Name,
#[serde(default)]
pub http: self::http::Config,
}