domani/README.md
2023-08-01 16:44:16 +02:00

6.4 KiB

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

Domani supports serving domains using the following protocols:

  • HTTP
  • HTTPS (with SSL certificates automatically retrieved using LetsEncrypt)
  • Gemini

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:

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

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 primary_domain of this server is automatically
  # included.
  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.
  #primary_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

    #proxied_domains:

      # An example built-in domain backed by an HTTP reverse-proxy to some
      # other web-service. 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:
      # * url must be to an http endpoint (not https)
      # * dns.resolver_addr is ignored and the system-wide dns is used
      #
      #proxy.example.com:
      #  url: "http://some.other.service.com"
      #
      #  # Extra headers to add to proxied requests
      #  request_headers:
      #    - name: Host
      #      value: "yet.another.service.com"
      #    - name: X-HEADER-TO-DELETE
      #      value: ""

  #gemini:

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

    #proxied_domains:

      # An example built-in domain backed by a reverse-proxy to some other
      # gemini server. Requests to this domain will have connections
      # transparently proxied to the backing server.
      #
      # Proxies are currently limited in the following ways:
      # * url must be to a gemini endpoint
      # * dns.resolver_addr is ignored and the system-wide dns is used
      #
      #proxy.example.com:
      #  url: "gemini://some.other.service.com"

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.