domani/README.md

# Domani

Domani is a self-hosted rust service which connects a DNS hostname to a data
backend (e.g. a git repository), all with no account needed. The user only
inputs their domain name, their desired backend, and then adds two entries to
their DNS server.

[Demo which may or may not be live](https://domani.mediocregopher.com)

Domani supports serving domains using the following protocols:

- HTTP
- HTTPS (with SSL certificates automatically retrieved using LetsEncrypt)
- [Gemini](https://gemini.circumlunar.space/)

Files are served as-is, with their extension being used to determine
Content-Type. If a directory is requested (e.g. `/some/dir/`) then `index.html`
will be requested if the protocol is HTTP, or `index.gmi` if the protocol is
gemini.

## Build

Domani uses nix flakes for building and setting up the development environment.

In order to create a release binary:

```
nix build
```

A statically compiled binary will be placed in the `result` directory.

## Configuration

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

  # builtins are domains whose configuration is built into domani. These domains
  # are not able to be configured via the web interface, and will be hidden from
  # it unless the `public` key is set to true.
  #builtins:

    # An example built-in domain backed by a git repo.
    #git.example.com:
      #kind: git
      #url: "https://somewhere.com/some/repo.git"
      #branch_name: main

      # If true then the built-in will be included in the web interface's
      # domain list, but will not be configurable in the web interface
      #public: false

  #proxied:

    # An example built-in domain backed by an gemini and HTTP reverse-proxies to
    # other backends.
    #
    # HTTP requests will be proxied to http_url, and gemini requests will be
    # proxied to gemini_url. Either can be null.
    #
    # HTTP requests to the backing service will automatically have
    # X-Forwarded-For and (if HTTPS) X-Forwarded-Proto headers added to them.
    #
    # Proxies are currently limited in the following ways:
    # * http_url must be to an http endpoint (not https)
    # * dns.resolver_addr is ignored and the system-wide dns is used
    #
    #example.com:

      #http_url: "http://some.other.service.com"
      #gemini_url: "gemini://some.other.service.com"

      # Extra headers to add to proxied requests
      #http_request_headers:
      #  - name: Host
      #    value: "yet.another.service.com"
      #  - name: X-HEADER-TO-DELETE
      #    value: ""

      # Set to true to prevent the domain from being served over https.
      #https_disabled: false

service:

  # Passphrase which must be given by users who are configuring new domains via
  # the web interface.
  #passphrase: REQUIRED

  # 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.
  #
  # A CNAME record with the interface_domain of this server is automatically
  # included, if it's not null itself.
  #dns_records:
    #- kind: A
    #  addr: 127.0.0.1

    #- kind: AAAA
    #  addr: ::1

    # NOTE that the name given here must resolve to the Domani server.
    #- kind: CNAME
    #  name: domain.com

  # 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.
  #
  # This can be set to null to disable the web interface entirely.
  #interface_domain: "localhost"

  #http:

    # The address to listen for HTTP requests on. This must use port 80 if
    # https_addr is set.
    #http_addr: "[::]:3080"

    # The address to listen for HTTPS requests on. Defaults to not having HTTP
    # enabled. You can enable HTTPS by setting this to "[::]:443".
    #https_addr: null

  #gemini:

    # The address to listen for gemini requests on. Set this to null to disable
    # gemini support.
    #gemini_addr: "[::]:3965"
```

The YAML config file can be passed to the Domani process via the `--config-path`
CLI parameter:

```
domani --config-path <path>
```

### HTTPS Support

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.

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

Domani uses nix flakes for building and setting up the development environment.
In order to open a shell with all necessary tooling (expected rust toolchain
versions, etc...) simply do:

```
cp config.yml.tpl config.yml
nix develop
```

Within the shell which opens you can do `cargo run` to start a local instance.

Using the default configuration, the domain `domani-test.localhost` should be
immediately available at:

* `http://domani-test.localhost:3080`
* `gemini://domani-test.localhost:3965`

## Roadmap

* Better web interface design.
* Tutorials aimed at beginner users.

* Support for more backends than just git repositories, including:
    * IPFS/IPNS
    * Small static files (e.g. for well-knowns)
    * Google Drive
    * Dropbox

* Automatic HTTP/gemtext rendering for markdown files.
* Automatic HTTP rendering for gemtext files.

* Ability to disable the web interface.
* Ability to disable HTTP completely.