0k-charms/apache/README.org

* Usage

Other services will often require a service managed with this charm to
act as a HTTP/HTTPS front-end. It can provide certificates with HTTPS.


** Domain assignment

Services using relation =web-proxy= or =publish-dir= will be required
to be assigned a domain name for the virtual host that will be
created.

*** Domain sources

This domain name can be set (in order of priority), the first source
giving a name will be taken.

- *Relation's options* (=web-proxy= or =publish-dir=)
  Using =domain= option, and optionally the deprecated
 =server-aliases= for additional names.

  #+begin_src yaml
  myservice:
    # ...
    relations:
      web-proxy:
        apache:
          domain: mydomain.org
          #server-aliases:
          #  - www.mydomain.org
          #  - pro.mydomain.org
  #+end_src
- *Apache service's options*, using a =service-domain-name= mapping:

  #+begin_src yaml
  myservice:
    # ...
  apache:
    options:
      service-domain-map:
        # ...
        myservice:
          - mydomain.org
          - www.mydomain.org
          - pro.mydomain.org
        # ...
  #+end_src

- *the service name* itself if is a domain name:

  #+begin_src yaml
  www.mydomain.org:
    # ...
  #+end_src

  Please note that this is not recommended, and will be deprecated.

*** Domain and alternate domains

Every source (except the one coming out from the domain name), can use
several ways to provide *more than one domain name*.

Please remember:
- At least one domain name needs to be provided
- and the first domain can't use wildcards and will be considered the main domain name.

If other domains are specified, they will be used as aliases, and
wildcard (using ~*~) is supported.

Additionally, bash braces expansion and regex matching are
available. Space separated YAML string or YAML sequences are
supported, also as mix of both.

As examples, notice the following are equivalent and will serve
=myservice= on the exact same set of domain names:

#+begin_src yaml
myservice:
  relations:
    web-proxy:
      domain:
        ## A yaml list
        - myservice.home.org
        - mydomain.org
        - www.mydomain.org
        - pro.mydomain.org
        - *.myservice.hop.org
#+end_src


#+begin_src yaml
myservice:
  # ... no domain set in relation
apache:
  options:
    service-domain-map:
      ## A yaml list as a mapping value
      myservice:
        - myservice.home.org
        - {,www.,pro.}mydomain.org  ## bash braces expansion used
        - *.myservice.hop.org
#+end_src

#+begin_src yaml
myservice:
  # ...
apache:
  options:
    service-domain-map:
      ## space separated YAML string and bash braces expansion
      myservice: myservice.home.org {,www.,pro.}mydomain.org *.myservice.hop.org
#+end_src

#+begin_src yaml
myservice:
  # ...
apache:
  options:
    service-domain-map:
      ## Leveraging bash braces expansion and regex replacement
      .*: {$0.home,{,www.,pro.}mydomain,*.$0.hop}.org
#+end_src

*** Domain mapping

You can automatically assign a domain to services in relation
=web-proxy= or =publish-dir= with services managed by this charm using
the =service-domain-name= option. For instance:

#+begin_src yaml
apache:
  options:
    service-domain-map:
      .*: $0.mydomain.org
#+end_src

Where ~mydomain.org~ stands for the domain where most of your services
will be served. You can override this behavior for some services:
- by adding a matching rule *before* the given rule.
- by specifying a =domain= in the relation's options.

first rule matching will end the mapping:

#+begin_src yaml
apache:
  options:
    service-domain-map:
      foo: www.mydomain.org
      bar: beta.myotherdomain.com
#+end_src

Allows to distribute services to domains quite freely.


** Adding basic authentication for password protected access

Any service using relation =web-proxy= or =publish-dir= can assign a
simple =Basic Auth= protection (which is safe and secure only on =https=):

#+begin_src yaml
myservice:
  # ...
  relations:
    web-proxy:
      apache:
        domain: mydomain.org
        creds:
          # USER: PASSWORD 
          foo: fooP4s5w0rd
          bar: barP4s5w0rd
#+end_src


* SSH Tunnel

On the server side, you can configure your compose file::

#+begin_src yaml
apache:
  options:
    ssh-tunnel:
      domain: ssh.domain.com     ## required
      #ssl: ...                  ## required, but automatically setup if you
                                 ## provide a ``cert-provider`` to ``apache``.
#+end_src


On the client side you should add this to your ``~/.ssh/config``::

#+begin_src conf-space
Host ssh.domain.com
    Port 443
    ProxyCommand proxytunnel -q -E -p ssh.domain.com:443 -d ssh.domain.com:22
    DynamicForward 1080
    ServerAliveInterval 60
#+end_src

If it doesn't work, you can do some checks thanks to this command::

#+begin_example
$ proxytunnel -E -p ssh.domain.com:443 -d ssh.domain.com:22 -v \
    -H "User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Win32)\n"
#+end_example